Skip to content

Commit 2dc9ce7

Browse files
aayush3011Aayush Kataria
aayush3011
and
Aayush Kataria
authored
Adding embedding policy changes for EGS (#46870)
* Adding embedding policy changes for EGS * Updating changelog * Updating changelog * Resolving comments * Resolving comments * Fixing builds --------- Co-authored-by: Aayush Kataria <aayushkataria@Aayushs-MacBook-Pro-2.local>
1 parent 3b5edc6 commit 2dc9ce7

6 files changed

Lines changed: 455 additions & 149 deletions

File tree

‎sdk/cosmos/azure-cosmos/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
### 4.16.0b3 (Unreleased)
44

55
#### Features Added
6+
* Added **preview** support for the optional `embeddingSource` field on entries in `vector_embedding_policy.vectorEmbeddings`, which allows the service to generate vector embeddings from the specified item paths. Requires the embedding-generation service to be enabled on the account. See [46870](https://github.com/Azure/azure-sdk-for-python/pull/46870)
67

78
#### Breaking Changes
89

‎sdk/cosmos/azure-cosmos/README.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -733,6 +733,62 @@ vector_embedding_policy = {
733733
}
734734
```
735735

736+
### Public Preview - Embedding Generation Service (EGS)
737+
738+
A vector embedding may optionally include an `embeddingSource` describing how the embedding is generated by the
739+
service. The source specifies the item paths whose values are embedded (`sourcePaths`), the embedding model
740+
deployment (`deploymentName`, `modelName`), the embedding service `endpoint`, and the `authType` used to call
741+
that endpoint (one of `ApiKey` or `Entra`).
742+
743+
The `endpoint` is the HTTPS URL of the Azure AI Foundry / Azure OpenAI resource that hosts the embedding model
744+
deployment named by `deploymentName` (for example, `https://<resource>.openai.azure.com/`). This is the
745+
model-serving endpoint, not the Cosmos account endpoint.
746+
747+
When `authType` is `Entra`, the Cosmos account's managed identity is used to call the embedding endpoint; that
748+
identity must be granted the appropriate role on the embedding resource (for example, `Cognitive Services OpenAI
749+
User`). The SDK is not in the call path, so role assignments on the application's identity do not affect this
750+
flow.
751+
752+
A vector embedding policy that includes an embedding source looks like this:
753+
```python
754+
vector_embedding_policy = {
755+
"vectorEmbeddings": [
756+
{
757+
"path": "/embedding",
758+
"dataType": "float32",
759+
"dimensions": 1536,
760+
"distanceFunction": "cosine",
761+
"embeddingSource": {
762+
"sourcePaths": [
763+
"/journal_title",
764+
"/title",
765+
"/toc_abstract",
766+
"/abstract",
767+
"/full_text"
768+
],
769+
"deploymentName": "text-embedding-3-small",
770+
"modelName": "text-embedding-3-small",
771+
"endpoint": "https://<resource>.openai.azure.com/",
772+
"authType": "ApiKey"
773+
}
774+
}
775+
]
776+
}
777+
```
778+
779+
A few service-side invariants are worth keeping in mind when using EGS:
780+
781+
* **`vectorIndexes[*].path` must match the embedding's `path`, not any `sourcePaths` entry.** In the example above,
782+
the indexable path is `/embedding`; the `sourcePaths` (`/journal_title`, `/title`, ...) are only the inputs that
783+
the service reads to compute the vector stored at `/embedding`.
784+
* **`embeddingSource` should be treated as fixed at container creation.** The vector embedding paths themselves
785+
are immutable via `replace_container`; the SDK currently does not test or guarantee that the sub-fields of
786+
`embeddingSource` (`sourcePaths`, `deploymentName`, `modelName`, `endpoint`, `authType`) can be safely modified
787+
after creation. Plan to set them once at creation time.
788+
* **RU cost on the write path.** When `embeddingSource` is configured, every insert and upsert incurs the
789+
additional work of calling the embedding endpoint, persisting the generated vector, and indexing it. This is a
790+
non-trivial new RU charge that should be accounted for during capacity planning.
791+
736792
Separately, vector indexes have been added to the already existing indexing_policy and only require two fields per index:
737793
the path to the relevant field to be used, and the type of index from the possible options - flat, quantizedFlat, or diskANN.
738794
A sample indexing policy with vector indexes would look like this:

‎sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,11 @@ async def create_container(
206206
note that analytical storage can only be enabled on Synapse Link enabled accounts.
207207
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container. Each vector
208208
embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and
209-
is generated for a particular distance function.
209+
is generated for a particular distance function. Each vector embedding may also include an optional
210+
**provisional** ``embeddingSource`` describing how the embedding is generated by the service.
211+
The source object supports
212+
``sourcePaths`` (list of item paths whose values are embedded), ``deploymentName``, ``modelName``,
213+
``endpoint`` (embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
210214
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
211215
the container.
212216
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -283,7 +287,11 @@ async def create_container( # pylint: disable=too-many-statements
283287
note that analytical storage can only be enabled on Synapse Link enabled accounts.
284288
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container. Each vector
285289
embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and
286-
is generated for a particular distance function.
290+
is generated for a particular distance function. Each vector embedding may also include an optional
291+
**provisional** ``embeddingSource`` describing how the embedding is generated by the service.
292+
The source object supports ``sourcePaths``
293+
(list of item paths whose values are embedded), ``deploymentName``, ``modelName``, ``endpoint``
294+
(embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
287295
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
288296
the container.
289297
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -347,7 +355,11 @@ async def create_container( # pylint:disable=docstring-should-be-keyword, too-ma
347355
note that analytical storage can only be enabled on Synapse Link enabled accounts.
348356
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container. Each vector
349357
embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and
350-
is generated for a particular distance function.
358+
is generated for a particular distance function. Each vector embedding may also include an optional
359+
**provisional** ``embeddingSource`` describing how the embedding is generated by the service.
360+
The source object supports ``sourcePaths``
361+
(list of item paths whose values are embedded), ``deploymentName``, ``modelName``, ``endpoint``
362+
(embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
351363
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
352364
the container.
353365
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -497,7 +509,11 @@ async def create_container_if_not_exists(
497509
note that analytical storage can only be enabled on Synapse Link enabled accounts.
498510
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container.
499511
Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying
500-
data type, and is generated for a particular distance function.
512+
data type, and is generated for a particular distance function. Each vector embedding may also include an
513+
optional **provisional** ``embeddingSource`` describing how the embedding is generated by the service.
514+
The source object supports
515+
``sourcePaths`` (list of item paths whose values are embedded), ``deploymentName``, ``modelName``,
516+
``endpoint`` (embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
501517
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
502518
the container.
503519
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -558,7 +574,11 @@ async def create_container_if_not_exists(
558574
note that analytical storage can only be enabled on Synapse Link enabled accounts.
559575
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container.
560576
Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying
561-
data type, and is generated for a particular distance function.
577+
data type, and is generated for a particular distance function. Each vector embedding may also include an
578+
optional **provisional** ``embeddingSource`` describing how the embedding is generated by the service.
579+
The source object supports
580+
``sourcePaths`` (list of item paths whose values are embedded), ``deploymentName``, ``modelName``,
581+
``endpoint`` (embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
562582
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
563583
the container.
564584
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -606,7 +626,11 @@ async def create_container_if_not_exists( # pylint:disable=docstring-should-be-k
606626
note that analytical storage can only be enabled on Synapse Link enabled accounts.
607627
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container.
608628
Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying
609-
data type, and is generated for a particular distance function.
629+
data type, and is generated for a particular distance function. Each vector embedding may also include an
630+
optional **provisional** ``embeddingSource`` describing how the embedding is generated by the service.
631+
The source object supports
632+
``sourcePaths`` (list of item paths whose values are embedded), ``deploymentName``, ``modelName``,
633+
``endpoint`` (embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
610634
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
611635
the container.
612636
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.

‎sdk/cosmos/azure-cosmos/azure/cosmos/database.py‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,11 @@ def create_container( # pylint:disable=docstring-missing-param
201201
`here: https://learn.microsoft.com/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet`
202202
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container.
203203
Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying
204-
data type, and is generated for a particular distance function.
204+
data type, and is generated for a particular distance function. Each vector embedding may also include an
205+
optional **provisional** ``embeddingSource`` describing how the embedding is generated by the service.
206+
The source object supports
207+
``sourcePaths`` (list of item paths whose values are embedded), ``deploymentName``, ``modelName``,
208+
``endpoint`` (embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
205209
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
206210
the container.
207211
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -274,7 +278,11 @@ def create_container( # pylint:disable=docstring-missing-param
274278
`here: https://learn.microsoft.com/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet`
275279
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container.
276280
Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying
277-
data type, and is generated for a particular distance function.
281+
data type, and is generated for a particular distance function. Each vector embedding may also include an
282+
optional **provisional** ``embeddingSource`` describing how the embedding is generated by the service.
283+
The source object supports
284+
``sourcePaths`` (list of item paths whose values are embedded), ``deploymentName``, ``modelName``,
285+
``endpoint`` (embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
278286
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
279287
the container.
280288
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -333,7 +341,11 @@ def create_container( # pylint:disable=docstring-missing-param, too-many-statem
333341
`here: https://learn.microsoft.com/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet`
334342
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container.
335343
Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying
336-
data type, and is generated for a particular distance function.
344+
data type, and is generated for a particular distance function. Each vector embedding may also include an
345+
optional **provisional** ``embeddingSource`` describing how the embedding is generated by the service.
346+
The source object supports
347+
``sourcePaths`` (list of item paths whose values are embedded), ``deploymentName``, ``modelName``,
348+
``endpoint`` (embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
337349
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
338350
the container.
339351
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -485,7 +497,11 @@ def create_container_if_not_exists( # pylint:disable=docstring-missing-param
485497
`here: https://learn.microsoft.com/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet`
486498
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container. Each vector
487499
embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and
488-
is generated for a particular distance function.
500+
is generated for a particular distance function. Each vector embedding may also include an optional
501+
**provisional** ``embeddingSource`` describing how the embedding is generated by the service.
502+
The source object supports ``sourcePaths``
503+
(list of item paths whose values are embedded), ``deploymentName``, ``modelName``, ``endpoint``
504+
(embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
489505
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
490506
the container.
491507
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -544,7 +560,11 @@ def create_container_if_not_exists( # pylint:disable=docstring-missing-param
544560
`here: https://learn.microsoft.com/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet`
545561
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container. Each vector
546562
embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and
547-
is generated for a particular distance function.
563+
is generated for a particular distance function. Each vector embedding may also include an optional
564+
**provisional** ``embeddingSource`` describing how the embedding is generated by the service.
565+
The source object supports ``sourcePaths``
566+
(list of item paths whose values are embedded), ``deploymentName``, ``modelName``, ``endpoint``
567+
(embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
548568
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
549569
the container.
550570
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.
@@ -589,7 +609,11 @@ def create_container_if_not_exists( # pylint:disable=docstring-missing-param, d
589609
`here: https://learn.microsoft.com/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet`
590610
:keyword dict[str, Any] vector_embedding_policy: The vector embedding policy for the container. Each vector
591611
embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and
592-
is generated for a particular distance function.
612+
is generated for a particular distance function. Each vector embedding may also include an optional
613+
**provisional** ``embeddingSource`` describing how the embedding is generated by the service.
614+
The source object supports ``sourcePaths``
615+
(list of item paths whose values are embedded), ``deploymentName``, ``modelName``, ``endpoint``
616+
(embedding service endpoint), and ``authType`` (one of ``ApiKey`` or ``Entra``).
593617
:keyword dict[str, Any] change_feed_policy: The change feed policy to apply 'retentionDuration' to
594618
the container.
595619
:keyword dict[str, Any] full_text_policy: **provisional** The full text policy for the container.

0 commit comments

Comments
 (0)