Skip to content

Commit 671d3b5

Browse files
gewarrengewarren
authored
Miscellaneous AI docs cleanup (#44899)
1 parent d5956b9 commit 671d3b5

File tree

5 files changed

+77
-71
lines changed

5 files changed

+77
-71
lines changed

‎docs/ai/ai-extensions.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,21 @@ ms.author: alexwolf
1010

1111
# Unified AI building blocks for .NET using Microsoft.Extensions.AI
1212

13-
The .NET ecosystem provides abstractions for integrating AI services into .NET applications and libraries using the <xref:Microsoft.Extensions.AI> and [`Microsoft.Extensions.AI.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.AI.Abstractions) libraries. The .NET team also enhanced the core `Microsoft.Extensions.*` libraries with these abstractions for .NET generative AI applications and libraries. In the sections ahead, you learn:
13+
The .NET ecosystem provides abstractions for integrating AI services into .NET applications and libraries using the <xref:Microsoft.Extensions.AI> libraries. The .NET team has also enhanced the core `Microsoft.Extensions` libraries with these abstractions for use in generative AI .NET applications and libraries. In the sections ahead, you learn:
1414

1515
- Core concepts and capabilities of the `Microsoft.Extensions.AI` libraries.
1616
- How to work with AI abstractions in your apps and the benefits they offer.
1717
- Essential AI middleware concepts.
1818

1919
For more information, see [Introduction to Microsoft.Extensions.AI](../core/extensions/artificial-intelligence.md).
2020

21-
## What is the Microsoft.Extensions.AI library?
21+
## What are the Microsoft.Extensions.AI libraries?
2222

23-
<xref:Microsoft.Extensions.AI> is a set of core .NET libraries created in collaboration with developers across the .NET ecosystem, including Semantic Kernel. These libraries provide a unified layer of C# abstractions for interacting with AI services, such as small and large language models (SLMs and LLMs), embeddings, and middleware.
23+
The `Microsoft.Extensions.AI` libraries provides core exchange types and abstractions for interacting with AI services, such as small and large language models (SLMs and LLMs). They also provide the ability to register services like logging and caching in your dependency injection (DI) container.
2424

2525
:::image type="content" source="media/ai-extensions/meai-architecture-diagram.png" lightbox="media/ai-extensions/meai-architecture-diagram.png" alt-text="An architectural diagram of the AI extensions libraries.":::
2626

27-
`Microsoft.Extensions.AI` provides abstractions that can be implemented by various services, all adhering to the same core concepts. This library is not intended to provide APIs tailored to any specific provider's services. The goal of `Microsoft.Extensions.AI` is to act as a unifying layer within the .NET ecosystem, enabling developers to choose their preferred frameworks and libraries while ensuring seamless integration and collaboration across the ecosystem.
27+
The `Microsoft.Extensions.AI` namespaces provide abstractions that can be implemented by various services, all adhering to the same core concepts. This library is not intended to provide APIs tailored to any specific provider's services. The goal of `Microsoft.Extensions.AI` is to act as a unifying layer within the .NET ecosystem, enabling developers to choose their preferred frameworks and libraries while ensuring seamless integration and collaboration across the ecosystem.
2828

2929
## Work with abstractions for common AI services
3030

@@ -34,9 +34,9 @@ AI capabilities are rapidly evolving, with patterns emerging for common function
3434
- Embedding generation to integrate with vector search capabilities.
3535
- Tool calling to integrate with other services, platforms, or code.
3636

37-
The `Microsoft.Extensions.AI` library provides abstractions for these types of tasks, so developers can focus on coding against conceptual AI capabilities rather than specific platforms or provider implementations. Unified abstractions are crucial for developers to work effectively across different sources.
37+
The `Microsoft.Extensions.AI.Abstractions` package provides abstractions for these types of tasks, so developers can focus on coding against conceptual AI capabilities rather than specific platforms or provider implementations. Unified abstractions are crucial for developers to work effectively across different sources.
3838

39-
For example, the `IChatClient` interface allows consumption of language models from various providers, whether you're connecting to an Azure OpenAI service or running a local Ollama installation. Any .NET package that provides an AI client can implement the `IChatClient` interface, enabling seamless integration with consuming .NET code:
39+
For example, the <xref:Microsoft.Extensions.AI.IChatClient> interface allows consumption of language models from various providers, such as an Azure OpenAI service or a local Ollama installation. Any .NET package that provides an AI client can implement the `IChatClient` interface to enable seamless integration with consuming .NET code:
4040

4141
```csharp
4242
IChatClient client =
@@ -45,7 +45,7 @@ IChatClient client =
4545
    new AzureAIInferenceChatClient(...);
4646
```
4747

48-
Then, regardless of the provider you're using, you can send requests as follows:
48+
Then, regardless of the provider you're using, you can send requests by calling <xref:Microsoft.Extensions.AI.IChatClient.CompleteAsync(System.Collections.Generic.IList{Microsoft.Extensions.AI.ChatMessage},Microsoft.Extensions.AI.ChatOptions,System.Threading.CancellationToken)>, as follows:
4949

5050
```csharp
5151
var response = await chatClient.CompleteAsync(
@@ -54,7 +54,7 @@ var response = await chatClient.CompleteAsync(
5454
Console.WriteLine(response.Message);
5555
```
5656

57-
These abstractions allow for idiomatic C# code for various scenarios with minimal code changes, whether you're using different services for development and production, addressing hybrid scenarios, or exploring other service providers.
57+
These abstractions allow for idiomatic C# code for various scenarios with minimal code changes. They make it easy to use different services for development and production, addressing hybrid scenarios, or exploring other service providers.
5858

5959
Library authors who implement these abstractions make their clients interoperable with the broader `Microsoft.Extensions.AI` ecosystem. Service-specific APIs remain accessible if needed, allowing consumers to code against the standard abstractions and pass through to proprietary APIs only when required.
6060

@@ -69,9 +69,9 @@ In the future, implementations of these `Microsoft.Extensions.AI` abstractions w
6969

7070
## Middleware implementations for AI services
7171

72-
Connecting to and using AI services is just one aspect of building robust applications. Production-ready applications require additional features like telemetry, logging, and tool-calling capabilities. The `Microsoft.Extensions.AI` abstractions enable you to easily integrate these components into your applications using familiar patterns.
72+
Connecting to and using AI services is just one aspect of building robust applications. Production-ready applications require additional features like telemetry, logging, caching, and tool-calling capabilities. The `Microsoft.Extensions.AI` packages provides APIs that enable you to easily integrate these components into your applications using familiar dependency injection and middleware patterns.
7373

74-
The following sample demonstrates how to register an OpenAI `IChatClient`. `IChatClient` allows you to attach the capabilities in a consistent way across various providers.
74+
The following sample demonstrates how to register an OpenAI `IChatClient`. You can attach capabilities in a consistent way across various providers by calling methods such as <xref:Microsoft.Extensions.AI.FunctionInvokingChatClientBuilderExtensions.UseFunctionInvocation(Microsoft.Extensions.AI.ChatClientBuilder,Microsoft.Extensions.Logging.ILoggerFactory,System.Action{Microsoft.Extensions.AI.FunctionInvokingChatClient})> on a <xref:Microsoft.Extensions.AI.ChatClientBuilder>.
7575

7676
```csharp
7777
app.Services.AddChatClient(builder => builder
@@ -82,16 +82,16 @@ app.Services.AddChatClient(builder => builder
8282
    .Use(new OpenAIClient(...)).AsChatClient(...));
8383
```
8484

85-
The capabilities demonstrated in this snippet are included in the `Microsoft.Extensions.AI` library, but they are only a small subset of the capabilities that can be layered in with this approach. .NET developers are able to expose many types of middleware to create powerful AI functionality.
85+
The capabilities demonstrated in this snippet are included in the `Microsoft.Extensions.AI` library, but they're only a small subset of the capabilities that can be layered in with this approach. .NET developers are able to expose many types of middleware to create powerful AI functionality.
8686

8787
## Build with Microsoft.Extensions.AI
8888

8989
You can start building with `Microsoft.Extensions.AI` in the following ways:
9090

91-
- **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.
92-
- **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 service.
93-
- **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.
94-
- **Ecosystem Contributors**: If you're interested in contributing to the ecosystem, consider writing custom middleware components.
91+
- **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.
92+
- **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 service.
93+
- **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.
94+
- **Ecosystem contributors**: If you're interested in contributing to the ecosystem, consider writing custom middleware components.
9595

9696
To get started, see the samples in the [dotnet/ai-samples](https://aka.ms/meai-samples) GitHub repository.
9797

‎docs/ai/dotnet-ai-ecosystem.md

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,19 @@ The .NET ecosystem provides many powerful tools, libraries, and services to deve
1313
> [!IMPORTANT]
1414
> Not all of the SDKs and services presented in this doc are maintained by Microsoft. When considering an SDK, make sure to evaluate its quality, licensing, support, and compatibility to ensure they meet your requirements.
1515
16-
## Microsoft.Extensions.AI library for .NET
16+
## Microsoft.Extensions.AI libraries
1717

18-
[`Microsoft.Extensions.AI`](ai-extensions.md) is a set of core .NET libraries created in collaboration with developers across the .NET ecosystem, including Semantic Kernel. These libraries provide a unified layer of C# abstractions for interacting with AI services, such as small and large language models (SLMs and LLMs), embeddings, and middleware.
18+
[`Microsoft.Extensions.AI`](ai-extensions.md) is a set of core .NET libraries that provide a unified layer of C# abstractions for interacting with AI services, such as small and large language models (SLMs and LLMs), embeddings, and middleware. These APIs were created in collaboration with developers across the .NET ecosystem, including Semantic Kernel. The low-level APIs, such as <xref:Microsoft.Extensions.AI.IChatClient> and <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2>, were extracted from Semantic Kernel and moved into the <xref:Microsoft.Extensions.AI> namespace.
1919

2020
`Microsoft.Extensions.AI` provides abstractions that can be implemented by various services, all adhering to the same core concepts. This library is not intended to provide APIs tailored to any specific provider's services. The goal of `Microsoft.Extensions.AI` is to act as a unifying layer within the .NET ecosystem, enabling developers to choose their preferred frameworks and libraries while ensuring seamless integration and collaboration across the ecosystem.
2121

2222
## Semantic Kernel for .NET
2323

24-
[Semantic Kernel](semantic-kernel-dotnet-overview.md) is an open-source SDK that enables AI integration and orchestration capabilities in your .NET apps. This SDK is generally the recommended AI orchestration tool for .NET apps that use one or more AI services in combination with other APIs or web services, data stores, and custom code. Semantic Kernel benefits enterprise developers in the following ways:
24+
If you just want to use the low-level services, such as <xref:Microsoft.Extensions.AI.IChatClient> and <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2>, you can reference the `Microsoft.Extensions.AI.Abstractions` package directly from your app. However, if you want to use higher-level, more opinionated approaches to AI, then you should use [Semantic Kernel](semantic-kernel-dotnet-overview.md).
25+
26+
Semantic Kernel, which has a dependency on the `Microsoft.Extensions.AI.Abstractions` package, is an open-source library that enables AI integration and orchestration capabilities in your .NET apps. Its connectors provides concrete implementations of <xref:Microsoft.Extensions.AI.IChatClient> and <xref:Microsoft.Extensions.AI.IEmbeddingGenerator`2> for different services, including OpenAI, Amazon Bedrock, and Google Gemini.
27+
28+
The Semantic Kernel SDK is generally the recommended AI orchestration tool for .NET apps that use one or more AI services in combination with other APIs or web services, data stores, and custom code. Semantic Kernel benefits enterprise developers in the following ways:
2529

2630
- Streamlines integration of AI capabilities into existing applications to enable a cohesive solution for enterprise products.
2731
- Minimizes the learning curve of working with different AI models or services by providing abstractions that reduce complexity.
@@ -31,7 +35,7 @@ For more information, see the [Semantic Kernel documentation](/semantic-kernel/o
3135

3236
## .NET SDKs for building AI apps
3337

34-
Many different SDKs are available for .NET to build apps with AI capabilities depending on the target platform or AI model. OpenAI models offer powerful generative AI capabilities, while other Azure AI Services provide intelligent solutions for a variety of specific scenarios.
38+
Many different SDKs are available to build .NET apps with AI capabilities depending on the target platform or AI model. OpenAI models offer powerful generative AI capabilities, while other Azure AI Services provide intelligent solutions for a variety of specific scenarios.
3539

3640
### .NET SDKs for OpenAI models
3741

@@ -45,9 +49,9 @@ Many different SDKs are available for .NET to build apps with AI capabilities de
4549

4650
Azure offers many other AI services to build specific application capabilities and workflows. Most of these services provide a .NET SDK to integrate their functionality into custom apps. Some of the most commonly used services are shown in the following table. For a complete list of available services and learning resources, see the [Azure AI Services](/azure/ai-services/what-are-ai-services) documentation.
4751

48-
| Service | Description |
49-
|---------------------------------------------------------------|------------------------------------------------------------|
50-
| [Azure AI Search](/azure/search/) | Bring AI-powered cloud search to your mobile and web apps. |
52+
| Service | Description |
53+
|-----------------------------------|----------------------------------------------|
54+
| [Azure AI Search](/azure/search/) | Bring AI-powered cloud search to your mobile and web apps. |
5155
| [Azure AI Content Safety](/azure/ai-services/content-safety/) | Detect unwanted or offensive content. |
5256
| [Azure AI Document Intelligence](/azure/ai-services/document-intelligence/) | Turn documents into intelligent data-driven solutions. |
5357
| [Azure AI Language](/azure/ai-services/language-service/) | Build apps with industry-leading natural language understanding capabilities. |
@@ -59,15 +63,15 @@ Azure offers many other AI services to build specific application capabilities a
5963

6064
.NET apps can also connect to local AI models for many different development scenarios. [Semantic Kernel](https://github.com/microsoft/semantic-kernel) is the recommended tool to connect to local models using .NET. Semantic Kernel can connect to many different models hosted across a variety of platforms and abstracts away lower-level implementation details.
6165

62-
For example, you can use [Ollama](https://ollama.com/) to [connect to local AI models with .NET](quickstarts/quickstart-local-ai.md), including several Small Language Models (SLMs) developed by Microsoft:
66+
For example, you can use [Ollama](https://ollama.com/) to [connect to local AI models with .NET](quickstarts/quickstart-local-ai.md), including several small language models (SLMs) developed by Microsoft:
6367

64-
| Model | Description |
65-
|---------------------|----------------------------------------------------------------------------------------|
68+
| Model | Description |
69+
|---------------------|-----------------------------------------------------------|
6670
| [phi3 models][phi3] | A family of powerful SLMs with groundbreaking performance at low cost and low latency. |
6771
| [orca models][orca] | Research models in tasks such as reasoning over user-provided data, reading comprehension, math problem solving, and text summarization. |
6872

6973
> [!NOTE]
70-
> The preceding SLMs can also be hosted on other services such as Azure.
74+
> The preceding SLMs can also be hosted on other services, such as Azure.
7175
7276
## Connect to vector databases and services
7377

@@ -77,10 +81,10 @@ For example, you can use [Ollama](https://ollama.com/) to [connect to local AI m
7781

7882
This article summarized the tools and SDKs in the .NET ecosystem, with a focus on services that provide official support for .NET. Depending on your needs and stage of app development, you might also want to take a look at the open-source options for the ecosystem in [the unofficial list of .NET + AI resources](https://github.com/jmatthiesen/dotnet-ai-resources?tab=readme-ov-file#models). Microsoft is not the maintainer of many of these projects, so be sure to review their quality, licensing, and support.
7983

80-
## Next Steps
84+
## Next steps
8185

8286
- [What is Semantic Kernel?](/semantic-kernel/overview/)
8387
- [Quickstart - Summarize text using Azure AI chat app with .NET](./quickstarts/quickstart-openai-summarize-text.md)
8488

8589
[phi3]: https://azure.microsoft.com/products/phi-3
86-
[orca]: https://www.microsoft.com/en-us/research/project/orca/
90+
[orca]: https://www.microsoft.com/research/project/orca/

0 commit comments

Comments
 (0)