eShopLite

eShopLite

eShopLite 是一组 .NET 参考应用，实现了一个电子商务网站，并包含语义搜索、模型上下文协议（MCP）、推理模型、向量数据库等功能。

• ☁️ 场景使用 .NET 和 Aspire，并以稳定的 .NET 10 为基线；另有一个独立的 .NET 11 RC2 场景，用于试验 Blazor AI 组件。有关兼容性例外，请参阅下方的依赖项基线。
• 🌟 别忘了**为此仓库加星（🌟）**，方便日后查找。
• ➡️ 通过**复刻此仓库**获取自己的副本，并在自己的仓库中找到它。
• ❓ 有疑问？ 除了创建问题或拉取请求，提问的最佳方式是加入 Azure AI Discord 频道，AI 专家团队可以为你提供帮助。

功能

此项目框架提供以下功能：

• 基于 Aspire 的现代 .NET 应用架构
• 多种搜索能力（关键词搜索、语义搜索）
• 集成多种 AI 模型（GPT-4o、DeepSeek-R1 等）
• 向量数据库实现（内存、Azure AI Search、Chroma DB 等）
• 实时音频功能
• 模型上下文协议（MCP）服务端和客户端实现

eShopLite 场景

该项目包含多个场景，用于演示不同的功能：

场景	描述	关键技术
01 - 语义搜索	一个参考 .NET 应用，实现了具备关键词搜索和语义搜索功能的电子商务网站。	Aspire、OpenAI GPT-4.1-mini、内存向量数据库
02 - Azure AI Search	实现了一个电子商务网站，支持使用 SQL 查询进行关键词搜索，并使用向量数据库和 Azure AI Search 进行语义搜索。	Azure AI Search、OpenAI Embeddings、SQL Server
03 - 实时音频	为电子商务网站扩展高级搜索功能，并通过 GPT-4o Realtime Audio API 提供实时音频能力。	GPT-4o Realtime Audio API、Blazor 音频、Aspire
04 - Chroma DB	使用 Chroma DB 实现语义搜索功能。Chroma DB 是一款专为 AI 应用设计的开源数据库。	Chroma DB、OpenAI Embeddings、.NET SDK
05 - DeepSeek-R1	展示 DeepSeek-R1 模型的集成，以增强语义理解和搜索能力。	DeepSeek-R1、Aspire、向量嵌入
06 - Model Context Protocol (MCP)	实现 Model Context Protocol (MCP)，通过 MCP 服务和 MCP 客户端进行高级 AI 交互。	Model Context Protocol、函数调用、SSE 事件
07 - 并发 Agent	展示并发 Agent 编排和高级 AI Agent 协作模式。	Aspire、多 Agent 系统、编排
08 - SQL Server 2025	展示在 SQL Database Engine 中使用向量搜索和向量索引	SQL Server 2025、向量搜索、向量索引
09 - Azure App Service	展示如何将 Aspire 多服务电子商务应用部署到 Azure App Service，使用 SQLite 存储数据并集成 AI 搜索。	Azure App Service、Aspire、OpenAI、SQLite
10 - A2A Network	展示 Aspire 中高级 Agent 间 (A2A) 通信和编排模式，包括多 Agent 协作与推理。	Aspire、多 Agent 系统、A2A Protocol
11 - GitHub Models	在本地运行期间使用 GitHub Models 进行本地优先的 AI 开发，并在部署后自动切换到 Azure OpenAI。	Aspire、GitHub Models、Azure OpenAI
12 - Azure Functions	提供可选的 Azure Functions 门面，用于语义搜索，并作为向量搜索的替代部署边界。	Azure Functions、Aspire、Azure OpenAI
13 - 使用 Foundry Local 的可观测性助手	使用本地优先的可观测性助手总结日志、跟踪记录和事件。	Aspire、OpenTelemetry、Foundry Local、Microsoft.Extensions.AI
14 - 产品探索 Copilot	将搜索转变为自然语言产品探索，并提供有依据的说明。	语义搜索、向量搜索、Microsoft.Extensions.AI
15 - 门店智能报告	生成每日业务和运营门店智能报告。	应用数据、遥测、AI 摘要、报告
16 - MCP 门店运营工具	将安全的门店功能作为 MCP 工具提供给 Agent 使用。	MCP、Aspire、应用 API、工具调用
17 - A2A 门店运营网络	展示专用 Agent 如何通过 A2A 围绕门店应用协作。	A2A、Microsoft Agent Framework、托管 Agent
18 - Blazor Agentic UI	实验性的流式购物助手，包含商品目录卡片和需经人工批准的购物车操作。	.NET 11 RC2、Blazor AI 组件、AG-UI、Microsoft Agent Framework、Aspire
刚开始了解 Scenario 18？先看它的三步快速入门，
然后浏览屏幕截图和
从博客到代码的演练。

入门

先决条件

• .NET 10 SDK 10.0.402，在根目录的 global.json 中固定
• Docker Desktop 或 Podman
• Azure Developer CLI (azd)（用于部署到 Azure）
• Git
• Aspire CLI：使用 dotnet tool install -g Aspire.Cli --version 13.6.1 安装（用于通过 aspire secret set 设置本地机密）

依赖基线

2026 年 10 月 14 日的更新将现有的 17 个场景（14-MAFDevUI 除外）升级到 Aspire 13.6.1 和最新的兼容 NuGet 版本。根目录 SDK 仍使用稳定版 .NET 10；Scenario 18 则覆盖该版本，使用 .NET 11 RC2 来支持实验性的 Blazor 组件。若要处理所有场景，请安装这两个 SDK。

此次更新包含 Microsoft.Extensions.AI 10.11.0、OpenTelemetry 1.19、 Microsoft Agent Framework 1.24.0、MCP 2.2.0，以及在使用时采用的 A2A 1.0.0-preview3。 如果没有稳定版替代项能提供所需功能，现有预览版依赖仍会保留为预览版。MCP SSE 传输和 A2A 文本部分已迁移到当前 API，而非仅更改包版本。

场景 08 和 12 有意保留最新的 EF Core 9 服务版本 9.0.21： 它们的 EFCore.SqlServer.VectorSearch 9.0.0 提供程序要求使用该 EF 主版本。其他使用 EF 的场景采用 10.0.13。本地 dotnet-ef 工具清单与对应的 EF 主版本保持一致。要将 SQL 向量提供程序升级到原生 EF 10，需要单独迁移向量实体和查询，不能混用 EF 9 关系程序集与 EF 10 测试。 直接引用的 PKCS 版本选用已修补的 10.0.13，而非存在漏洞的传递依赖版本。

MAFDevUI 场景随后在满足 Azure MCP 先决条件后，完成了兼容的依赖和 API 迁移。 其构建和 27 项测试均已通过，其中包括离线 DevUI/Responses 集成测试。 使用 Azure CLI 身份验证和更新后的已保存 API 密钥进行的实时验证也已通过，涵盖嵌入、库存工具、流式工作流和全部三个结账层级。 身份验证模式的编排器检查也确认没有回退。 可选的 Foundry 托管 Agent 尚未验证。其他 17 个现有场景解决方案均已通过构建和现有测试（共 80 项测试），Scenario 18 也有 29 项测试通过。Scenario 18 还在本地通过 SQL Server 2025、真实 Foundry 嵌入和通过 Responses 调用的 gpt-6-luna 完成了验证：包括流式目录卡片、购物车拒绝/批准、缺失的产品规格，以及使用现有数据重启。这些检查并不能证明可以部署到云端，也未使用真实模型验证其他所有场景。

有关新场景、依赖迁移、设置脚本和已知升级边界，请参阅 CHANGELOG.md。

在本地启动场景

每个场景都有自己的 aspire.config.json，因此 Aspire 会选择该场景的 AppHost，而不会继承仓库根目录的选择：

cd .\scenarios\18-BlazorAgenticUI
aspire start

使用 aspire run 启动前台会话，并使用 aspire stop 停止所选应用。 请安装该场景最近的 global.json 所要求的 SDK：稳定版场景需要 .NET 10.0.402，Scenario 18 则需要 .NET 11 RC2。安装 .NET 11 并不能满足稳定版 .NET 10 的固定版本要求。选择 AppHost 不会安装 SDK 或配置凭据。

若要在不启动服务的情况下验证每个场景的本地选择：

pwsh .\scripts\Tests\Test-ScenarioAppHosts.ps1

安装

1. 克隆仓库：

   git clone https://github.com/Azure-Samples/eShopLite.git
   

2. 进入感兴趣的场景目录：

   cd eShopLite/scenarios/[scenario-folder]
   

3. 登录 Azure：

   azd auth login
   

4. 预配并部署所有资源：

   azd up
   

   系统会提示你提供一个 azd 环境名称（例如“eShopLite”），从 Azure 帐户中选择一个订阅，并选择一个可用所需模型（如 gpt-4.1-mini 和 ADA-002 的区域，示例区域为“eastus2”。

共享 Microsoft Foundry 模型和本地机密

使用 PowerShell 7 并通过 az login 登录。新的设置脚本会创建或重复使用一个 AIServices 帐户，部署通用聊天和嵌入模型，然后通过 Aspire CLI 配置本地 AppHost 用户机密。请提供你自己的订阅、资源组、全局唯一的帐户名称和区域：

pwsh .\scripts\Initialize-FoundryModels.ps1 `
  -SubscriptionId '<subscription-id>' `
  -ResourceGroupName 'rg-eshoplite' `
  -AccountName '<globally-unique-account-name>' `
  -Location 'eastus2' `
  -DryRun

移除 -DryRun 以预配资源并写入机密。这可能会产生 Azure 费用。 -DryRun 和 -WhatIf 不会调用 Azure，也不会确认模型是否可用。

默认聊天模型和部署名称为 gpt-6-luna；嵌入使用 text-embedding-3-small。脚本会从区域目录中解析模型版本， 并在预配前检查 SKU 支持情况和配额。如果请求的模型不可用，脚本会停止运行， 不会自动替换模型。你可以使用相应的 -Chat* 和 -Embeddings* 参数覆盖模型/版本、部署名称、SKU 或容量。 脚本会重复使用匹配的部署，并拒绝覆盖冲突的部署，也不会在禁用密钥身份验证的帐户上启用该功能。

此操作会预配本地开发所需的通用模型依赖项，而非每个场景的全部基础设施。SQL/容器仍由各自的 AppHost 管理；Azure AI Search、实时音频、DeepSeek、GitHub Models 和其他专用依赖项仍需按各自场景进行设置。此操作不会更改 azd up 使用的模型声明。

为现有部署配置密钥

配置密钥需要使用每个 AppHost 最近的 global.json 所指定的 SDK。 脚本会在请求密钥前检查 SDK 是否可用。如果使用非标准 SDK 安装路径，请传入 -DotNetRoot "<SDK installation directory>"；此覆盖仅适用于子命令。Aspire 退出代码 7 可能表示缺少 SDK，而非 Azure 身份验证问题。场景 18 明确要求 .NET 11 RC2。

现有的 scripts\Set-AzureOpenAISecrets.ps1 仅配置密钥，不会创建 Azure 资源。它会查找所有 eShopAppHost.csproj，包括不含 src 的目录结构， 并自动纳入未来的场景。场景 18（18-BlazorAgenticUI）拥有自己的 AppHost 和独立的 user-secrets 存储，并会自动纳入。没有 AppHost 的目录会报告为已跳过。从仓库根目录运行：

pwsh .\scripts\Set-AzureOpenAISecrets.ps1

脚本会以交互方式提示输入以下四个值：

提示	参数集
Azure OpenAI endpoint	Parameters:AzureOpenAIEndpoint
Azure OpenAI API key（已屏蔽）	Parameters:AzureOpenAIApiKey
Chat 部署名称（默认值为 gpt-6-luna）	Parameters:AzureOpenAIDeploymentName
Embeddings 部署名称（默认值为 text-embedding-3-small）	Parameters:AzureOpenAIEmbeddingsDeploymentName

使用 -DryRun 预览命令，但不执行：

pwsh .\scripts\Set-AzureOpenAISecrets.ps1 -DryRun

如需在不提示输入或提供 API key 的情况下预览：

pwsh .\scripts\Set-AzureOpenAISecrets.ps1 `
  -Endpoint 'https://<your-resource>.openai.azure.com/' -NonInteractive -DryRun

非交互式写入还需要 -ApiKey，其值必须是 SecureString，并通过已屏蔽的提示或安全凭据来源提供，而不能使用命令历史记录中的明文密钥。 本地 .NET user-secrets 并非加密的生产密钥存储。

在内部，脚本会为发现的每个 AppHost 调用 Aspire CLI（aspire secret set）。如需手动设置单个值，请直接使用相同的命令：

aspire secret set Parameters:AzureOpenAIEndpoint "https://<your-resource>.openai.azure.com/" \
  --apphost scenarios/01-SemanticSearch/src/eShopAppHost/eShopAppHost.csproj

注意： 场景专用的额外参数（例如，03-RealtimeAudio 中的 Parameters:AzureOpenAIRealtimeDeploymentName、05-deepseek 中的 Parameters:DeepSeekEndpoint、11-GitHubModels 中的 Parameters:GitHubModelsToken）仍须手动设置。详情请参阅各场景的 README。

快速入门

1. 导航至特定场景文件夹（例如，scenarios/01-SemanticSearch/）
2. 按照该场景文件夹中的 README 说明操作
3. 在相应的主机项目文件夹中运行 dotnet run，启动解决方案

演示

运行演示，请按以下步骤操作：

1. 导航至特定场景文件夹
2. 按照该场景 README 中的“运行解决方案”说明操作
3. 通过控制台输出中提供的 URL 访问应用程序

示例应用程序

以下是正在运行并执行关键词搜索的 eShopLite 应用程序：

以下是正在运行并执行语义搜索的 eShopLite 应用程序：

以下是正在运行并使用实时音频功能的 eShopLite 应用程序：

以下是正在使用 DeepSeek-R1 推理模型的 eShopLite 应用程序：

Aspire 仪表板可用于查看正在运行的服务：

包含所有已部署服务的 Azure 资源组：

资源

• 面向初学者的 .NET 生成式 AI

• Aspire 文档

• Azure OpenAI 服务文档

获取帮助

如果您在构建 AI 应用时遇到困难或有疑问，请加入：

如果您在构建过程中有产品反馈或遇到错误，请访问：