Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

AI docs edit pass #44628

Merged
merged 2 commits into from
Feb 1, 2025
Merged

AI docs edit pass #44628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca4e452
AI docs touchups
gewarren Jan 30, 2025
98c6881
add prefix
gewarren Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 15 additions & 14 deletions docs/ai/ai-extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ ms.author: alexwolf

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

The .NET ecosystem provides abstractions for integrating AI services into .NET applications and libraries using the [`Microsoft.Extensions.AI`](https://www.nuget.org/packages/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:
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:

- Core concepts and capabilities of the `Microsoft.Extensions.AI` libraries.
- How to work with AI abstractions in your apps and the benefits they offer.
Expand All @@ -20,7 +20,7 @@ For more information, see [Introduction to Microsoft.Extensions.AI](../core/exte

## What is the Microsoft.Extensions.AI library?

`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.
<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.

:::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.":::

Expand All @@ -40,18 +40,18 @@ For example, the `IChatClient` interface allows consumption of language models f

```csharp
IChatClient client =
    environment.IsDevelopment ?
    new OllamaChatClient(...) :
    new AzureAIInferenceChatClient(...);
    environment.IsDevelopment ?
    new OllamaChatClient(...) :
    new AzureAIInferenceChatClient(...);
```

Then, regardless of the provider you're using, you can send requests as follows:

```csharp
var response = await chatClient.CompleteAsync(
      "Translate the following text into Pig Latin: I love .NET and AI");
var response = await chatClient.CompleteAsync(
      "Translate the following text into Pig Latin: I love .NET and AI");

Console.WriteLine(response.Message);
Console.WriteLine(response.Message);
```

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.
Expand All @@ -69,17 +69,17 @@ In the future, implementations of these `Microsoft.Extensions.AI` abstractions w

## Middleware implementations for AI services

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.
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.

The following sample demonstrates how to register an OpenAI `IChatClient`. `IChatClient` allows you to attach the capabilities in a consistent way across various providers.

```csharp
app.Services.AddChatClient(builder => builder
app.Services.AddChatClient(builder => builder
    .UseLogging()
.UseFunctionInvocation()
.UseDistributedCache()   
.UseOpenTelemetry()
    .Use(new OpenAIClient(...)).AsChatClient(...));
.UseFunctionInvocation()
.UseDistributedCache()   
.UseOpenTelemetry()
    .Use(new OpenAIClient(...)).AsChatClient(...));
```

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.
Expand All @@ -92,6 +92,7 @@ You can start building with `Microsoft.Extensions.AI` in the following ways:
- **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.
- **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.

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

For an end-to-end sample using `Microsoft.Extensions.AI`, see [eShopSupport](https://github.com/dotnet/eShopSupport).
Expand Down
10 changes: 6 additions & 4 deletions docs/ai/azure-ai-services-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ var kernel = builder.Build();

Using keys is a straightforward option, but this approach should be used with caution. Keys aren't the recommended authentication option because they:

- Don't follow [the principle of least privilege](/entra/identity-platform/secure-least-privileged-access)—they provide elevated permissions regardless of who uses them or for what task.
- Don't follow [the principle of least privilege](/entra/identity-platform/secure-least-privileged-access). They provide elevated permissions regardless of who uses them or for what task.
- Can accidentally be checked into source control or stored in unsafe locations.
- Can easily be shared with or sent to parties who shouldn't have access.
- Often require manual administration and rotation.
Expand All @@ -47,19 +47,21 @@ Instead, consider using [Microsoft Entra ID](/#explore-microsoft-entra-id) for a

Microsoft Entra ID is a cloud-based identity and access management service that provides a vast set of features for different business and app scenarios. Microsoft Entra ID is the recommended solution to connect to Azure OpenAI and other AI services and provides the following benefits:

- Key-less authentication using [identities](/entra/fundamentals/identity-fundamental-concepts).
- Role-based-access-control (RBAC) to assign identities the minimum required permissions.
- Keyless authentication using [identities](/entra/fundamentals/identity-fundamental-concepts).
- Role-based access control (RBAC) to assign identities the minimum required permissions.
- Can use the [`Azure.Identity`](/dotnet/api/overview/azure/identity-readme) client library to detect [different credentials across environments](/dotnet/api/azure.identity.defaultazurecredential) without requiring code changes.
- Automatically handles administrative maintenance tasks such as rotating underlying keys.

The workflow to implement Microsoft Entra authentication in your app generally includes the following:
The workflow to implement Microsoft Entra authentication in your app generally includes the following steps:

- Local development:

1. Sign-in to Azure using a local dev tool such as the Azure CLI or Visual Studio.
1. Configure your code to use the [`Azure.Identity`](/dotnet/api/overview/azure/identity-readme) client library and `DefaultAzureCredential` class.
1. Assign Azure roles to the account you signed-in with to enable access to the AI service.

- Azure-hosted app:

1. Deploy the app to Azure after configuring it to authenticate using the `Azure.Identity` client library.
1. Assign a [managed identity](/entra/identity/managed-identities-azure-resources/overview) to the Azure-hosted app.
1. Assign Azure roles to the managed identity to enable access to the AI service.
Expand Down
27 changes: 15 additions & 12 deletions docs/ai/dotnet-ai-ecosystem.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,26 +45,26 @@ Many different SDKs are available for .NET to build apps with AI capabilities de

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.

| Service | Description |
| --- | --- |
| [Azure AI Search](/azure/search/) | Bring AI-powered cloud search to your mobile and web apps. |
| [Azure AI Content Safety](/azure/ai-services/content-safety/) | Detect unwanted or offensive content. |
| Service | Description |
|---------------------------------------------------------------|------------------------------------------------------------|
| [Azure AI Search](/azure/search/) | Bring AI-powered cloud search to your mobile and web apps. |
| [Azure AI Content Safety](/azure/ai-services/content-safety/) | Detect unwanted or offensive content. |
| [Azure AI Document Intelligence](/azure/ai-services/document-intelligence/) | Turn documents into intelligent data-driven solutions. |
| [Azure AI Language](/azure/ai-services/language-service/) | Build apps with industry-leading natural language understanding capabilities. |
| [Azure AI Speech](/azure/ai-services/speech-service/) | Speech to text, text to speech, translation, and speaker recognition. |
| [Azure AI Translator](/azure/ai-services/translator/) | AI-powered translation technology with support for more than 100 languages and dialects. |
| [Azure AI Vision](/azure/ai-services/computer-vision/) | Analyze content in images and videos. |
| [Azure AI Language](/azure/ai-services/language-service/) | Build apps with industry-leading natural language understanding capabilities. |
| [Azure AI Speech](/azure/ai-services/speech-service/) | Speech to text, text to speech, translation, and speaker recognition. |
| [Azure AI Translator](/azure/ai-services/translator/) | AI-powered translation technology with support for more than 100 languages and dialects. |
| [Azure AI Vision](/azure/ai-services/computer-vision/) | Analyze content in images and videos. |

## Develop with local AI models

.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.

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:

| Model | Description |
| --- | --- |
| [phi3 models](https://azure.microsoft.com/products/phi-3) | A family of powerful SLMs with groundbreaking performance at low cost and low latency. |
| [orca models](https://www.microsoft.com/en-us/research/project/orca/) | Research models in tasks such as reasoning over user given data, reading comprehension, math problem solving, and text summarization. |
| Model | Description |
|---------------------|----------------------------------------------------------------------------------------|
| [phi3 models][phi3] | A family of powerful SLMs with groundbreaking performance at low cost and low latency. |
| [orca models][orca] | Research models in tasks such as reasoning over user-provided data, reading comprehension, math problem solving, and text summarization. |

> [!NOTE]
> The preceding SLMs can also be hosted on other services such as Azure.
Expand All @@ -81,3 +81,6 @@ This article summarized the tools and SDKs in the .NET ecosystem, with a focus o

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

[phi3]: https://azure.microsoft.com/products/phi-3
[orca]: https://www.microsoft.com/en-us/research/project/orca/
6 changes: 3 additions & 3 deletions docs/ai/get-started-app-chat-scaling-with-azure-container-apps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ ms.custom: devx-track-dotnet, devx-track-dotnet-ai

## Prerequisites

* Azure subscription. [Create one for free](https://azure.microsoft.com/free/ai-services?azure-portal=true)
* Azure subscription. [Create one for free](https://azure.microsoft.com/free/ai-services?azure-portal=true).
* Access granted to Azure OpenAI in the desired Azure subscription.

Currently, access to this service is granted only by application. You should [apply for access](https://aka.ms/oai/access) to Azure OpenAI.
Currently, access to this service is granted only by application. You should [apply for access](https://aka.ms/oai/access) to Azure OpenAI.

* [Dev containers](https://containers.dev/) are available for both samples, with all dependencies required to complete this article. You can run the dev containers in GitHub Codespaces (in a browser) or locally using Visual Studio Code.

Expand All @@ -26,7 +26,7 @@ ms.custom: devx-track-dotnet, devx-track-dotnet-ai

#### [Visual Studio Code](#tab/visual-studio-code)

* [Docker Desktop](https://www.docker.com/products/docker-desktop/) - start Docker Desktop if it's not already running
* [Docker Desktop](https://www.docker.com/products/docker-desktop/) - Start Docker Desktop if it's not already running
* [Visual Studio Code](https://code.visualstudio.com/)
* [Dev Container Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)

Expand Down
Loading