<!--
{
  "availability" : [
    "iOS: 17.0.0 -",
    "iPadOS: 17.0.0 -",
    "macCatalyst: 17.0.0 -",
    "macOS: 14.0.0 -",
    "tvOS: 17.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "NaturalLanguage",
  "identifier" : "/documentation/NaturalLanguage/NLContextualEmbedding",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Natural Language"
    ],
    "preciseIdentifier" : "c:objc(cs)NLContextualEmbedding"
  },
  "title" : "NLContextualEmbedding"
}
-->

# NLContextualEmbedding

A model that computes sequences of embedding vectors for natural language utterances.

```
class NLContextualEmbedding
```

## Overview

`NLContextualEmbedding` provides a dense vector representation of natural language utterances
using models trained with contextualized language understanding. Unlike static word embeddings provided
by `NLEmbedding`, contextual embeddings dynamically adjust based on surrounding words, enabling
deeper language comprehension.

If you are building text classification or word tagging models, you can use
`NLContextualEmbedding` with <doc://com.apple.documentation/documentation/CreateML>
by selecting <doc://com.apple.documentation/documentation/CreateML/MLTextClassifier/FeatureExtractorType/bertEmbedding> as the feature extraction component in your model. For more information on how to create your own text
classification model refer to <doc://com.apple.documentation/documentation/CreateML/creating-a-text-classifier-model>.

> Note: For semantic similarity tasks, consider using ``doc://com.apple.naturallanguage/documentation/NaturalLanguage/NLEmbedding``. To learn more on how to
> implement semantic similarity, refer to <doc://com.apple.documentation/documentation/NaturalLanguage/finding-similarities-between-pieces-of-text>.

Before configuring your contextual embedding:

- Select a model that’s appropriate for your target language when initializing the embedding.
- Call [`requestAssets(completionHandler:)`](/documentation/NaturalLanguage/NLContextualEmbedding/requestAssets(completionHandler:)) before computing the embedding to confirm assets are available.

Some models support multiple languages; for example, you can use the same object to compute
embeddings for both English and Spanish. However, this isn’t always the case — languages like
English and Chinese may require separate models. For more information about supported
languages, refer to [`languages`](/documentation/NaturalLanguage/NLContextualEmbedding/languages).

## Topics

### Creating a contextual embedding

[`init(modelIdentifier:)`](/documentation/NaturalLanguage/NLContextualEmbedding/init(modelIdentifier:))

Creates a contextual embedding from a model identifier.

[`init(language:)`](/documentation/NaturalLanguage/NLContextualEmbedding/init(language:))

Creates a contextual embedding from a language.

[`init(script:)`](/documentation/NaturalLanguage/NLContextualEmbedding/init(script:))

Creates a contextual embedding from a script.

### Discovering available contextual embeddings

[`contextualEmbeddings(forValues:)`](/documentation/NaturalLanguage/NLContextualEmbedding/contextualEmbeddings(forValues:))

Returns contextual embedding models that match the specified language, script, or revision criteria.

### Inspecting the contextual embedding

[`dimension`](/documentation/NaturalLanguage/NLContextualEmbedding/dimension)

The dimensionality of the embedding vectors generated by the model.

[`hasAvailableAssets`](/documentation/NaturalLanguage/NLContextualEmbedding/hasAvailableAssets)

A Boolean value that indicates whether assets are available on-device.

[`languages`](/documentation/NaturalLanguage/NLContextualEmbedding/languages)

The languages that the contextual embedding supports.

[`maximumSequenceLength`](/documentation/NaturalLanguage/NLContextualEmbedding/maximumSequenceLength)

The maximum number of tokens in sequence for which the embedding generates vectors.

[`modelIdentifier`](/documentation/NaturalLanguage/NLContextualEmbedding/modelIdentifier)

A string that uniquely identifies the embedding model.

[`revision`](/documentation/NaturalLanguage/NLContextualEmbedding/revision)

The version number the contextual embedding uses.

[`scripts`](/documentation/NaturalLanguage/NLContextualEmbedding/scripts)

The writing systems that the language uses.

### Requesting assets

[`requestAssets(completionHandler:)`](/documentation/NaturalLanguage/NLContextualEmbedding/requestAssets(completionHandler:))

Requests embedding model assets and downloads them if available.

[`NLContextualEmbedding.AssetsResult`](/documentation/NaturalLanguage/NLContextualEmbedding/AssetsResult)

The availability of the contextual embedding model assets.

### Loading and unloading assets

[`load()`](/documentation/NaturalLanguage/NLContextualEmbedding/load())

The instance method that loads the embedding model.

[`unload()`](/documentation/NaturalLanguage/NLContextualEmbedding/unload())

The instance method that unloads the embedding model.

### Applying an embedding

[`embeddingResult(for:language:)`](/documentation/NaturalLanguage/NLContextualEmbedding/embeddingResult(for:language:))

Applies an embedding to a string and obtains the resulting embedding vectors.

[`NLContextualEmbeddingResult`](/documentation/NaturalLanguage/NLContextualEmbeddingResult)

An object that represents the embedding vector result from applying a contextual embedding to a string.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)