技术速递｜使用 AI 应用模板扩展创建一个 .NET AI 应用与自定义数据进行对话

摘要：在本快速入门中，你将学习如何使用 .NET AI 应用模板创建一个 .NET AI 应用，与自定义数据进行对话。该模板旨在简化 .NET 构建 AI 应用的上手体验，帮助你处理常见的设置任务和配置。

在本快速入门中，你将学习如何使用 .NET AI 应用模板创建一个 .NET AI 应用，与自定义数据进行对话。该模板旨在简化 .NET 构建 AI 应用的上手体验，帮助你处理常见的设置任务和配置。

先决条件

.NET 9.0 SDK

https://dotnet.microsoft.com/download/?wt.mc_id=3reg_webpage_reactor

以下任一 IDE（可选）：

Visual Studio 2022

https://visualstudio.microsoft.com/?wt.mc_id=3reg_webpage_reactor

安装了 C# Dev Kit 的 Visual Studio Code

https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit/?wt.mc_id=3reg_webpage_reactor

https://code.visualstudio.com/?wt.mc_id=3reg_webpage_reactor

安装 .NET AI 应用模板

AI Chat Web App 模板通过 NuGet 以模板包的形式提供。使用 dotnet new install 命令安装该包：

dotnet new install Microsoft.Extensions.AI.Templates

dotnet new install

https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new-install/?wt.mc_id=3reg_webpage_reactor

创建 .NET AI 应用

安装 AI 应用模板后，你可以通过 Visual Studio 界面、Visual Studio Code 或 .NET CLI 来创建入门应用。

Visual Studio

1. 在 Visual Studio 中，导航到 文件 > 新建 > 项目。

2. 在“创建新项目”界面中，搜索 AI Chat Web App，选择匹配的结果并点击下一步。

3. 在“配置新项目”界面中，输入项目名称和位置，然后点击下一步。

4. 在“附加信息”界面：

Framework选项选择.NET 9.0。

AI service provider选项选择GitHub Models。

Vector store选项选择本地磁盘存储（用于原型开发）。

5. 点击创建完成操作。

Visual Studio Code

在 Visual Studio Code 中打开命令面板。

搜索 New project，并选择结果.NET: New Project。

在项目模板列表中搜索 AI进行筛选。

选择 AI Chat Web App并按Enter。

注意

命令面板目前仅支持默认设置。若要在创建模板时配置 AI 平台和向量存储，请使用 Visual Studio 或 .NET CLI 的工作流。

.NET CLI

1. 在终端窗口中，导航到设备上的一个空目录。

2. 使用 dotnet new命令和以下参数创建一个新应用：

dotnet new aichatweb --Framework net9.0 --provider githubmodels --vector-store local

该命令会根据你指定的配置创建一个新的 .NET 9.0 应用。

3. 在你喜欢的编辑器（例如 Visual Studio Code）中打开新应用：

code .

探索示例应用

你创建的示例应用是一个 Blazor Interactive ServerWeb 应用，预先配置了常见的 AI 和数据服务。该应用已为你处理了以下内容：

在 csproj文件中包含了必要的Microsoft.Extensions.AI包及其他依赖，帮助你快速开始 AI 开发。

在 Program.cs文件中创建并注册多个可用于依赖注入的 AI 服务：

IChatClient服务：用于与生成式 AI 模型进行对话。

IEmbeddingGenerator服务：用于生成嵌入向量，这是向量搜索功能的核心。

JsonVectorStore：作为内存中的向量存储。

注册一个 SQLite 数据库上下文服务来处理文档导入。应用已预配置为会自动导入你添加到项目 Data文件夹中的文档（包括示例文件）。

提供一个完整的基于 Blazor 组件的聊天 UI。该 UI 支持 AI 响应的富文本格式，并提供例如结果引用等功能。

GitHub Models：配置对 GitHub Models 的访问

要在代码中访问 GitHub Models，你需要创建一个 GitHub 个人访问 token：

打开 GitHub 账户设置中 Developer Settings下的Personal access tokens页面。

选择 Generate new token。

输入 token 名称，在 Permissions中将Models权限设置为Access: Read-only。

在页面底部选择 Generate token。

复制生成的 token，后续步骤中会使用。

创建一个 GitHub 个人访问 token

https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token/?wt.mc_id=3reg_webpage_reactor

Azure OpenAI：创建并认证 Azure OpenAI 服务

要在 .NET AI 模板中使用 Azure OpenAI，你需要创建并认证一个 Azure OpenAI 服务。

创建 Azure OpenAI 服务

如果你尚未拥有 Azure OpenAI 服务资源，请先创建一个。

将 gpt-4o-mini和text-embedding-3-small模型部署到你的 Azure OpenAI 服务资源。在创建这些部署时，请将部署名称与模型名称保持一致（gpt-4o-mini和），以匹配模板的默认值。有关如何部署模型，请参阅 Azure OpenAI 文档中的创建资源。

创建一个

https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/create-resource?pivots=web-portal/?wt.mc_id=3reg_webpage_reactor

创建资源

https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/create-resource?pivots=web-portal#deploy-a-model/?wt.mc_id=3reg_webpage_reactor

认证 Azure OpenAI 服务

AI 模板使用 Microsoft Entra ID实现无密钥、无缝认证。它利用 DefaultAzureCredential 在本地运行时自动检测并使用开发工具中的证书。要连接到服务，请确保你的开发者账户已分配适当的角色，并已登录到本地开发工具。

1. 为开发者账户分配角色以访问 Azure OpenAI 资源：

在 Azure Portal中，导航到你的 Azure OpenAI 资源的概览页面。

从左侧导航选择 Access control (IAM)。

为你的 Azure 账户添加 Azure AI Developer 角色分配。

2. 使用已分配 Azure AI Developer角色的 Azure 账户登录本地开发工具，如 Visual Studio 或 Azure CLI。

DefaultAzureCredential

https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential/?wt.mc_id=3reg_webpage_reactor

角色分配

https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication/local-development-dev-accounts#assign-roles-to-the-group/?wt.mc_id=3reg_webpage_reactor

登录本地开发工具

https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication/local-development-dev-accounts#sign-in-to-azure-using-developer-tooling/?wt.mc_id=3reg_webpage_reactor

配置应用

AI Chat Web App在创建完成后几乎可以立即运行。但你需要配置应用，以便使用为 GitHub Models 设置的个人访问 token。默认情况下，应用模板会在项目的本地 .NET 用户机密中查找该值。你可以通过 Visual Studio 界面或 .NET CLI 来管理用户机密。

注意

若你使用 Azure OpenAI 服务，为避免认证错误，请确保你已使用在 Azure OpenAI 资源上被分配 Azure AI Developer角色的用户登录 Visual Studio 或 Azure CLI。

Visual Studio

在 Visual Studio 中，右键点击 Solution Explorer中的项目，选择Manage User Secrets。这会打开一个secrets.json文件，你可以在其中存储 API 密钥，而不会被纳入版本控制。

添加以下键值对：

{ "GitHubModels:Token": "}

.NET CLI

dotnet user-secrets set GitHubModels:Token your-personal-access-token>

默认情况下，应用模板使用 gpt-4o-mini和text-embedding-3-small模型。若要尝试其他模型，请在Program.cs中更新名称参数：

var chatClient = ghModelsClient.AsChatClient("gpt-4o-mini");var embeddingGenerator = ghModelsClient.AsEmbeddingGenerator("text-embedding-3-small");

运行并测试应用

1. 在 Visual Studio 顶部点击运行按钮启动应用。片刻后，你应该会在浏览器中看到如下 UI 加载：