# nw-smart-store

**Repository Path**: daxnet/nw-smart-store

## Basic Information

- **Project Name**: nw-smart-store
- **Description**: 一个基于Semantic Kernel、RAG和MCP Agent实现的销售业务AI智能应答系统案例
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-19
- **Last Updated**: 2025-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Northwind 智能商店助手
这是一个智能商店示例应用程序，演示了基于著名 Northwind 数据库的 NL-to-SQL AI智能应答系统。

![Screenshot](docs/screenshot.png)

根据 [此处](https://github.com/yugabyte/yugabyte-db/wiki/Northwind-Sample-Database) 的描述，Northwind数据库是：

>Northwind 数据库是一个古老的示例数据库，最初由微软创建，数十年来一直被用作其各种数据库产品教程的基础。Northwind 数据库包含一家名为“Northwind Traders”的虚构公司的销售数据，该公司从事全球特色食品的进出口业务。Northwind 数据库是一个优秀的小型企业 ERP 教程架构，包含客户、订单、库存、采购、供应商、运输、员工和单式记账等数据。

Northwind 数据库的实体关系模型 (ERM) 如下：

![Northwind ER 模型图](docs/northwind_er.jpg)

此示例应用程序的目标是实现一个自然语言到 SQL 的解决方案，使最终用户能够使用自然语言（例如英语、中文等）与系统对话，并获得库存和销售数据的全面解释。

## 架构

本示例使用 LLM（大型语言模型）结合 RAG 和 MCP 代理来实现自然语言到 SQL 的转换和 SQL 执行，以提供结构化数据反馈，从而将搜索结果包含在聊天响应消息中。

以下数据流图 (DFD) 展示了该解决方案的基本架构：

![Data Flow Diagram](docs/arch.svg)

以下序列是用户查询往返的工作流程：

![Sequence Diagram](docs/query_seq.svg)

## 框架、工具和技术

示例应用程序使用了以下框架、工具和技术：

- 开发：Microsoft Visual Studio 2022
- 编程：Microsoft Visual C#, Github Copilot
- .NET: Microsoft .NET 9
- 后端：
    - Microsoft ASP.NET Core Web API
    - Microsoft Semantic Kernel
    - ModelContextProtocol with ASP.NET hosting
    - AI LLMs: Microsoft Azure AI Foundry
        - Chat Completion: gpt-4.1
        - Embedding: text-embedding-3-large
    - Vector Database: Qdrant
    - Relational Database: PostgreSQL
- 前端：
    - Blazor WebAssembly
    - [Ant Design Blazor](https://antblazor.com/) 组件库

![Tech Word Cloud](docs/tech_word_cloud.png)

## 开始使用

您可以通过 docker compose 直接运行此示例应用，也可以使用 Microsoft Visual Studio 2022 调试和开发应用。

### 从Docker运行

首先，请确保您已安装 Docker（Linux 下的 Docker Daemon 或 Windows/MacOS 上的 Docker Desktop）。

使用以下步骤构建 Docker 镜像：

```bash
$ git clone https://gitee.com/daxnet/nw-smart-store
$ cd nw-smart-store/docker
$ docker compose build
```

构建所有 Docker 镜像后，在同一目录下创建一个 Docker 环境文件，其中包含所需的环境变量。例如：

```bash
$ vim dev.env
```

此文件应包含以下环境变量设置：

```text
CHAT_DEPLOYMENT=<Azure AI Foundry 中部署的聊天完成模型的名称>
CHAT_ENDPOINT=<Azure AI Foundry 中部署的聊天完成模型的端点>
CHAT_APIKEY=<Azure AI Foundry 中部署的聊天完成模型的 API 密钥>
EMBEDDING_DEPLOYMENT=<Azure AI Foundry 中部署的嵌入模型的名称>
EMBEDDING_ENDPOINT=<Azure AI Foundry 中部署的嵌入模型的端点>
EMBEDDING_APIKEY=<Azure AI Foundry 中部署的嵌入模型的 API 密钥>
```

请记住将 `<>` 中的值替换为 Azure AI Foundry 模型设置中的值。

> 注意：目前，此示例应用程序仅支持部署在 Azure AI Foundry 上的 LLM，Ollama 暂不支持。如果您想探索 Ollama，请克隆此代码库并自行开发。

之后，使用以下命令启动应用程序：

```bash
$ docker compose --env-file dev.env up
```

请注意，`dev.env` 是您上面创建的 docker 环境文件的名称。

所有容器运行完成后，启动一个新的 shell，执行以下命令对参考文档进行初始索引（矢量化和嵌入）：

```bash
$ curl -X POST http://localhost:5030/api/search/build-index
```

这将提示您索引已成功创建，然后您就可以开始了。

> 如果您下次修改了参考文档（`northwind_schema.en.json` 或 `northwind_schema.cn.json`）并希望重建索引/重新向量化参考文档，则应改用 `curl -X POST http://localhost:5030/api/search/build-index?force=true`。

> 首次初始化 PostgreSQL 数据库容器时，它会自动导入 Northwind 数据库，因此您会看到大量“INSERT”消息。

打开网络浏览器，导航至 “http://localhost:8082” 以打开聊天窗口。

### 从 Visual Studio 运行（调试）

首先，您需要提供所需的环境变量：

```text
nss__ai__chat__deployment=<Azure AI Foundry 中部署的聊天完成模型的名称>
nss__ai__chat__endpoint=<Azure AI Foundry 中部署的聊天完成模型的端点>
nss__ai__chat__apikey=<Azure AI Foundry 中部署的聊天完成模型的 API 密钥>
nss__ai__embedding__deployment=<Azure AI Foundry 中部署的嵌入模型的名称>
nss__ai__embedding__endpoint=<Azure AI Foundry 中部署的嵌入模型的端点>
nss__ai__embedding__apikey=<Azure AI Foundry 中部署的嵌入模型的 API 密钥>
```

您可以通过将它们设置为您的操作系统环境变量，或通过编辑`Nss.ApiService/appsettings.Development.json` 文件。

然后执行以下命令启动用于开发的 Docker 容器：

```bash
$ cd nw-smart-store/docker
$ docker compose -f docker-compose.dev.yaml up
```

> 首次启动时，PostgreSQL 数据库容器初始化时会自动导入 Northwind 数据库，因此您会在控制台中看到大量“INSERT”消息。

然后在 Visual Studio 中打开解决方案文件 `nss.sln` ，同时启动以下项目：

- Nss.ApiService
- Nss.McpServer
- Nss.WebApp

所有程序运行完成后，启动一个新的 shell，执行以下命令对参考文档进行初始索引（矢量化和嵌入）：

```bash
$ curl -X POST http://localhost:5030/api/search/build-index
```

这将提示您索引已成功创建，您可以开始操作了。

> 如果您下次修改了参考文档（`northwind_schema.en.json`或`northwind_schema.cn.json`），并希望重建索引/重新矢量化参考文档，则应改用`curl -X POST http://localhost:5030/api/search/build-index?force=true`。

您的聊天窗口应该已经在默认浏览器中打开。如果没有，请导航至 `http://localhost:5282`

## 参考资料

- [Northwind database for Postgres](https://github.com/pthom/northwind_psql)
- [Building a Model Context Protocol Server with Semantic Kernel](https://devblogs.microsoft.com/semantic-kernel/building-a-model-context-protocol-server-with-semantic-kernel/)
- [Ant Design Blazor official web site](https://antblazor.com)
- [Building a RAG API with .NET, Semantic Kernel, Phi-3, and Qdrant: Enrich Your E-commerce Experience](https://elguerre.com/2025/04/22/%F0%9F%9A%80-building-a-rag-api-with-net-semantic-kernel-phi-3-and-qdrant-enrich-your-e-commerce-experience/)