Merge pull request #46918 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

docs/ai/advanced/sample-implementations.md

@@ -0,0 +1,38 @@
+---
+title: "Sample implementations of IChatClient and IEmbeddingGenerator"
+description: Learn more about the IChatClient and IEmbeddingGenerator interfaces, see simple implementations, and find links to concrete implementations.
+ms.topic: article
+ms.date: 05/28/2025
+---
+
+# Sample implementations of IChatClient and IEmbeddingGenerator
+
+.NET libraries that provide clients for language models and services can provide implementations of the <xref:Microsoft.Extensions.AI.IChatClient> and <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2> interfaces. Any consumers of the interfaces are then able to interoperate seamlessly with these models and services via the abstractions.
+
+## The `IChatClient` interface
+
+The <xref:Microsoft.Extensions.AI.IChatClient> interface defines a client abstraction responsible for interacting with AI services that provide chat capabilities. It includes methods for sending and receiving messages with multi-modal content (such as text, images, and audio), either as a complete set or streamed incrementally. Additionally, it allows for retrieving strongly typed services provided by the client or its underlying services.
+
+The following sample implements `IChatClient` to show the general structure.
+
+:::code language="csharp" source="./snippets/sample-implementations/SampleChatClient.cs":::
+
+For more realistic, concrete implementations of `IChatClient`, see:
+
+- [AzureAIInferenceChatClient.cs](https://github.com/dotnet/extensions/blob/main/src/Libraries/Microsoft.Extensions.AI.AzureAIInference/AzureAIInferenceChatClient.cs)
+- [OpenAIChatClient.cs](https://github.com/dotnet/extensions/blob/main/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs)
+- [Microsoft.Extensions.AI chat clients](https://github.com/dotnet/extensions/tree/main/src/Libraries/Microsoft.Extensions.AI/ChatCompletion)
+
+## The `IEmbeddingGenerator<TInput,TEmbedding>` interface
+
+The <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2> interface represents a generic generator of embeddings. Here, `TInput` is the type of input values being embedded, and `TEmbedding` is the type of generated embedding, which inherits from the <xref:Microsoft.Extensions.AI.Embedding> class.
+
+The `Embedding` class serves as a base class for embeddings generated by an `IEmbeddingGenerator<TInput,TEmbedding>`. It's designed to store and manage the metadata and data associated with embeddings. Derived types, like `Embedding<T>`, provide the concrete embedding vector data. For example, an `Embedding<float>` exposes a `ReadOnlyMemory<float> Vector { get; }` property for access to its embedding data.
+
+The `IEmbeddingGenerator<TInput,TEmbedding>` interface defines a method to asynchronously generate embeddings for a collection of input values, with optional configuration and cancellation support. It also provides metadata describing the generator and allows for the retrieval of strongly typed services that can be provided by the generator or its underlying services.
+
+The following code shows how the `SampleEmbeddingGenerator` class implements the `IEmbeddingGenerator<TInput,TEmbedding>` interface. It has a primary constructor that accepts an endpoint and model ID, which are used to identify the generator. It also implements the <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2.GenerateAsync(System.Collections.Generic.IEnumerable{`0},Microsoft.Extensions.AI.EmbeddingGenerationOptions,System.Threading.CancellationToken)> method to generate embeddings for a collection of input values.
+
+:::code language="csharp" source="./snippets/sample-implementations/SampleEmbeddingGenerator.cs":::
+
+This sample implementation just generates random embedding vectors. For a more realistic, concrete implementation, see [OpenTelemetryEmbeddingGenerator.cs](https://github.com/dotnet/extensions/blob/main/src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGenerator.cs).

docs/ai/advanced/snippets/sample-implementations/Implementations.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" Version="9.5.0" />
+  </ItemGroup>
+
+</Project>

docs/ai/snippets/microsoft-extensions-ai/AI.Shared/SampleChatClient.cs renamed to docs/ai/advanced/snippets/sample-implementations/SampleChatClient.cs

@@ -1,9 +1,11 @@
 using System.Runtime.CompilerServices;
 using Microsoft.Extensions.AI;
 
-public sealed class SampleChatClient(Uri endpoint, string modelId) : IChatClient
+public sealed class SampleChatClient(Uri endpoint, string modelId)
+    : IChatClient
 {
-    public ChatClientMetadata Metadata { get; } = new(nameof(SampleChatClient), endpoint, modelId);
+    public ChatClientMetadata Metadata { get; } =
+        new(nameof(SampleChatClient), endpoint, modelId);
 
     public async Task<ChatResponse> GetResponseAsync(
         IEnumerable<ChatMessage> chatMessages,

docs/ai/snippets/microsoft-extensions-ai/AI.Shared/SampleEmbeddingGenerator.cs renamed to docs/ai/advanced/snippets/sample-implementations/SampleEmbeddingGenerator.cs

@@ -16,10 +16,10 @@ public async Task<GeneratedEmbeddings<Embedding<float>>> GenerateAsync(
         await Task.Delay(100, cancellationToken);
 
         // Create random embeddings.
-        return new GeneratedEmbeddings<Embedding<float>>(
-            from value in values
+        return [.. from value in values
             select new Embedding<float>(
-                Enumerable.Range(0, 384).Select(_ => Random.Shared.NextSingle()).ToArray()));
+                Enumerable.Range(0, 384)
+                .Select(_ => Random.Shared.NextSingle()).ToArray())];
     }
 
     public object? GetService(Type serviceType, object? serviceKey) =>

docs/ai/microsoft-extensions-ai.md

@@ -43,15 +43,14 @@ The following subsections show specific [IChatClient](#the-ichatclient-interface
 
 The following sections show specific [IEmbeddingGenerator](#the-iembeddinggenerator-interface) usage examples:
 
-- [Sample implementation](#sample-implementation)
 - [Create embeddings](#create-embeddings)
 - [Pipelines of functionality](#pipelines-of-functionality)
 
 ### The `IChatClient` interface
 
 The <xref:Microsoft.Extensions.AI.IChatClient> interface defines a client abstraction responsible for interacting with AI services that provide chat capabilities. It includes methods for sending and receiving messages with multi-modal content (such as text, images, and audio), either as a complete set or streamed incrementally. Additionally, it allows for retrieving strongly typed services provided by the client or its underlying services.
 
-.NET libraries that provide clients for language models and services can provide an implementation of the `IChatClient` interface. Any consumers of the interface are then able to interoperate seamlessly with these models and services via the abstractions.
+.NET libraries that provide clients for language models and services can provide an implementation of the `IChatClient` interface. Any consumers of the interface are then able to interoperate seamlessly with these models and services via the abstractions. You can see a simple implementation at [Sample implementations of IChatClient and IEmbeddingGenerator](advanced/sample-implementations.md).
 
 #### Request a chat response
 
@@ -195,25 +194,13 @@ If you don't know ahead of time whether the service is stateless or stateful, yo
 
 ### The `IEmbeddingGenerator` interface
 
-The <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2> interface represents a generic generator of embeddings. Here, `TInput` is the type of input values being embedded, and `TEmbedding` is the type of generated embedding, which inherits from the <xref:Microsoft.Extensions.AI.Embedding> class.
+The <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2> interface represents a generic generator of embeddings. For the generic type parameters, `TInput` is the type of input values being embedded, and `TEmbedding` is the type of generated embedding, which inherits from the <xref:Microsoft.Extensions.AI.Embedding> class.
 
-The `Embedding` class serves as a base class for embeddings generated by an `IEmbeddingGenerator`. It's designed to store and manage the metadata and data associated with embeddings. Derived types, like `Embedding<T>`, provide the concrete embedding vector data. For example, an `Embedding<float>` exposes a `ReadOnlyMemory<float> Vector { get; }` property for access to its embedding data.
+The `Embedding` class serves as a base class for embeddings generated by an `IEmbeddingGenerator`. It's designed to store and manage the metadata and data associated with embeddings. Derived types, like <xref:Microsoft.Extensions.AI.Embedding`1>, provide the concrete embedding vector data. For example, an `Embedding<float>` exposes a `ReadOnlyMemory<float> Vector { get; }` property for access to its embedding data.
 
 The `IEmbeddingGenerator` interface defines a method to asynchronously generate embeddings for a collection of input values, with optional configuration and cancellation support. It also provides metadata describing the generator and allows for the retrieval of strongly typed services that can be provided by the generator or its underlying services.
 
-#### Sample implementation
-
-The following sample implementation of `IEmbeddingGenerator` shows the general structure.
-
-:::code language="csharp" source="snippets/microsoft-extensions-ai/AI.Shared/SampleEmbeddingGenerator.cs":::
-
-The preceding code:
-
-- Defines a class named `SampleEmbeddingGenerator` that implements the `IEmbeddingGenerator<string, Embedding<float>>` interface.
-- Has a primary constructor that accepts an endpoint and model ID, which are used to identify the generator.
-- Implements the `GenerateAsync` method to generate embeddings for a collection of input values.
-
-The sample implementation just generates random embedding vectors. You can find a concrete implementation in the [📦 Microsoft.Extensions.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) package.
+Most users don't need to implement the `IEmbeddingGenerator` interface. However, if you're a library author, you can see a simple implementation at [Sample implementations of IChatClient and IEmbeddingGenerator](advanced/sample-implementations.md).
 
 #### Create embeddings
 
@@ -247,7 +234,7 @@ In this way, the `RateLimitingEmbeddingGenerator` can be composed with other `IE
 
 You can start building with `Microsoft.Extensions.AI` in the following ways:
 
-- **Library developers**: If you own libraries that provide clients for AI services, consider implementing the interfaces in your libraries. This allows users to easily integrate your NuGet package via the abstractions.
+- **Library developers**: If you own libraries that provide clients for AI services, consider implementing the interfaces in your libraries. This allows users to easily integrate your NuGet package via the abstractions. For example implementations, see [Sample implementations of IChatClient and IEmbeddingGenerator](advanced/sample-implementations.md).
 - **Service consumers**: If you're developing libraries that consume AI services, use the abstractions instead of hardcoding to a specific AI service. This approach gives your consumers the flexibility to choose their preferred provider.
 - **Application developers**: Use the abstractions to simplify integration into your apps. This enables portability across models and services, facilitates testing and mocking, leverages middleware provided by the ecosystem, and maintains a consistent API throughout your app, even if you use different services in different parts of your application.
 - **Ecosystem contributors**: If you're interested in contributing to the ecosystem, consider writing custom middleware components.

docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.AddMessages/ConsoleAI.AddMessages.csproj

@@ -7,6 +7,10 @@
     <Nullable>enable</Nullable>
   </PropertyGroup>
 
+  <ItemGroup>
+    <PackageReference Include="OllamaSharp" Version="5.1.19" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\AI.Shared\AI.Shared.csproj" />
   </ItemGroup>

docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.AddMessages/Program.cs

@@ -1,7 +1,8 @@
 using Microsoft.Extensions.AI;
+using OllamaSharp;
 
-IChatClient client = new SampleChatClient(
-    new Uri("http://coolsite.ai"), "target-ai-model");
+IChatClient client = new OllamaApiClient(
+    new Uri("http://localhost:11434/"), "phi3:mini");
 
 // <Snippet1>
 List<ChatMessage> history = [];

docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.ConsumeClientMiddleware/ConsoleAI.ConsumeClientMiddleware.csproj

@@ -9,6 +9,7 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.0-preview.5.25277.114" />
+    <PackageReference Include="OllamaSharp" Version="5.1.19" />
     <ProjectReference Include="..\AI.Shared\AI.Shared.csproj" />
   </ItemGroup>
 

docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.ConsumeClientMiddleware/Program.cs

@@ -3,12 +3,17 @@
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
+using OllamaSharp;
 
 // <SnippetUse>
 HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
 
+IChatClient client = new OllamaApiClient(
+    new Uri("http://localhost:11434/"),
+    "phi3:mini");
+
 builder.Services.AddChatClient(services =>
-    new SampleChatClient(new Uri("http://localhost"), "test")
+        client
         .AsBuilder()
         .UseDistributedCache()
         .UseRateLimiting()

docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.ConsumeRateLimitingEmbedding/ConsoleAI.ConsumeRateLimitingEmbedding.csproj

@@ -7,6 +7,10 @@
     <Nullable>enable</Nullable>
   </PropertyGroup>
 
+  <ItemGroup>
+    <PackageReference Include="OllamaSharp" Version="5.1.19" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\AI.Shared\AI.Shared.csproj" />
   </ItemGroup>