[Embedding V0] AzureOpenAIEmbeddingGenerator ΓÇö provider implementation

Part of: #5830 (V0 embedding generation).

Background

This is the concrete IEmbeddingGenerator implementation that lives inside the Microsoft.Azure.Cosmos.AI package. It wraps Azure.AI.OpenAI's EmbeddingClient to generate text embeddings, and is wired up from VectorEmbeddingPolicy.Embedding.EmbeddingSource (endpoint, deploymentName, authType) or from explicit constructor parameters.

Reference implementation exists in the CosmosDB monorepo at:
/Product/Cosmos/EmbeddingGenerator/Service/Providers/AzureOpenAITextEmbeddingProvider.cs
(adapt ΓÇö do not copy verbatim; the monorepo class has service-side concerns not relevant here).

Public API

namespace Microsoft.Azure.Cosmos.AI
{
    /// <summary>
    /// IEmbeddingGenerator implementation backed by Azure OpenAI.
    /// Construct from an EmbeddingSource (read from VectorEmbeddingPolicy) or
    /// provide endpoint/deployment/credential directly.
    /// </summary>
    public sealed class AzureOpenAIEmbeddingGenerator : IEmbeddingGenerator, IDisposable
    {
        // Constructor 1: from VectorEmbeddingPolicy EmbeddingSource + ApiKey
        public AzureOpenAIEmbeddingGenerator(EmbeddingSource source, string apiKey);

        // Constructor 2: from VectorEmbeddingPolicy EmbeddingSource + TokenCredential (Entra)
        public AzureOpenAIEmbeddingGenerator(EmbeddingSource source, TokenCredential credential);

        // Constructor 3: explicit params + ApiKey (for customers not using VectorEmbeddingPolicy)
        public AzureOpenAIEmbeddingGenerator(string endpoint, string deploymentName, int dimensions, string apiKey);

        // Constructor 4: explicit params + TokenCredential (Entra)
        public AzureOpenAIEmbeddingGenerator(string endpoint, string deploymentName, int dimensions, TokenCredential credential);

        public Task<IEnumerable<ReadOnlyMemory<double>>> GenerateEmbeddingsAsync(
            IEnumerable<string> text,
            CancellationToken cancellationToken = default);

        public void Dispose();
    }
}

Behavioral requirements

1. Batching: if the input list is longer than the Azure OpenAI batch limit (2048 items), split into multiple requests automatically and concatenate results in order.
2. Dimensions: use the dimensions parameter from EmbeddingSource (or constructor arg) when calling EmbeddingGenerationOptions.Dimensions so the output vector size matches the container policy.
3. Return type: materialize each OpenAI.Embeddings.Embedding float value to double, wrap in ReadOnlyMemory<double>.
4. Auth:
   • ApiKey path: new AzureOpenAIClient(endpoint, new AzureKeyCredential(apiKey))
   • Entra path: new AzureOpenAIClient(endpoint, tokenCredential)
5. Error handling: surface Azure SDK RequestFailedException as CosmosException (HTTP 503) with innerException preserved and an actionable message identifying the embedding endpoint + deployment.
6. Thread safety: EmbeddingClient is thread-safe; multiple concurrent calls are allowed.
7. Dispose: disposes the underlying AzureOpenAIClient if it was created internally.

Acceptance criteria

• Unit tests (in test project) cover:
  • Happy path: single batch, returns correct count and double[] values.
  • Multi-batch: input > batch limit, two API calls made, results concatenated in order.
  • Wrong dimensions in response ΓåÆ wraps as CosmosException.
  • RequestFailedException ΓåÆ wrapped as CosmosException with inner exception.
  • Constructed from EmbeddingSource (round-trip: source ΓåÆ client ΓåÆ call).
  • Dispose called on the underlying client exactly once.
• API surface matches the public constructors above.
• AzureOpenAIEmbeddingGenerator works end-to-end when set on QueryRequestOptions.EmbeddingGenerator against an emulator running a hybrid-search query (covered by [Embedding V0] Emulator tests + baseline regeneration #5837).

Files likely touched

• Microsoft.Azure.Cosmos.AI/src/AzureOpenAIEmbeddingGenerator.cs (new)
• Microsoft.Azure.Cosmos.AI/tests/.../AzureOpenAIEmbeddingGeneratorTests.cs (new)

Dependencies

• Package scaffold ([Embedding V0] New Microsoft.Azure.Cosmos.Embedding package — scaffold #5841
• EmbeddingSource model ([Embedding V0] DTO additions + new QueryFeatures.EmbeddingGeneration bit #5832 / VectorEmbeddingPolicy issue)
• IEmbeddingGenerator interface ([Embedding V0] Public surface: IEmbeddingGenerator + QueryRequestOptions.EmbeddingGenerator #5831 ΓÇö done, merged in PR EmbeddingGenerator: Adds ICosmosEmbeddingGenerator client-wide configuration (preview) #5838)