From 9ff7d02143563e15896acfd56515b5fc4a1603f5 Mon Sep 17 00:00:00 2001 From: ShaoHua <345265198@qqcom> Date: Fri, 27 Feb 2026 00:07:48 +0800 Subject: [PATCH] update README.md --- README.md | 440 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 379 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index f884d7a..4f38d39 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,87 @@ -# MilvusDemo +# VectorDBDemo + +一个基于 .NET 9 的向量数据库与自然语言函数调用示例集合，展示现代 C# 在 AI 相关领域的应用。 + +## 目录 + +- [项目简介](#项目简介) +- [技术栈](#技术栈) +- [项目结构](#项目结构) +- [快速开始](#快速开始) +- [MilvusDemo](#milvusdemo) + - [功能特性](#功能特性) + - [模块划分](#模块划分) + - [运行示例](#运行示例) + - [API 说明](#api-说明) +- [VoiceToFunctionDemo](#voicetofunctiondemo) + - [功能特性](#功能特性-1) + - [内置函数](#内置函数) + - [运行示例](#运行示例-1) + - [扩展开发](#扩展开发) +- [开发指南](#开发指南) +- [常见问题](#常见问题) +- [贡献指南](#贡献指南) + +## 项目简介 + +本项目包含两个独立的示例项目，分别演示了不同的技术场景： + +1. **MilvusDemo** - 演示如何使用 C# 与 Milvus 向量数据库进行交互，包括集合管理、索引创建、数据插入和向量搜索 +2. **VoiceToFunctionDemo** - 演示如何将自然语言指令解析为函数调用，支持参数提取和类型验证 + +## 技术栈 + +- **.NET 9.0** - 使用最新的 .NET 平台 +- **C# 12** - 现代化的 C# 语法特性 +- **Milvus.Client** (v2.3.0-preview.1) - Milvus 向量数据库的 .NET 客户端 +- **Newtonsoft.Json** (v12.0.1) - JSON 序列化支持 + +## 项目结构 + +``` +VectorDBDemo/ +├── MilvusDemo/ # Milvus 向量数据库示例 +│ ├── Program.cs # 程序入口，提供交互式菜单 +│ ├── MilvusService.cs # Milvus 服务封装 +│ ├── MilvusServiceTests.cs # 模拟测试实现 +│ ├── TestRunner.cs # 测试运行器 +│ └── MilvusDemo.csproj # 项目配置 +├── VoiceToFunctionDemo/ # 语音转函数调用示例 +│ ├── Program.cs # 程序入口和示例演示 +│ ├── FunctionInfo.cs # 函数信息定义 +│ ├── ParsedResult.cs # 解析结果模型 +│ ├── User.cs # 用户实体类 +│ └── VoiceToFunctionDemo.csproj # 项目配置 +├── .vscode/ # VS Code 配置 +├── .gitea/ # CI/CD 配置 +└── VectorDBDemo.slnx # 解决方案文件 +``` + +## 快速开始 + +### 环境要求 + +- .NET SDK 9.0 或更高版本 +- （可选）Milvus Server - 仅在运行 MilvusDemo 的实际连接模式时需要 + +### 安装 .NET 9 + +访问 [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) 下载并安装 .NET 9 SDK。 + +### 构建项目 + +```powershell +# 构建整个解决方案 +dotnet build + +# 或构建特定项目 +dotnet build MilvusDemo +dotnet build VoiceToFunctionDemo +``` + +--- + +## MilvusDemo 一个使用 C#（.NET 9）与 `Milvus.Client` 的极简示例项目，演示： - 初始化集合（存在则删除并重建） @@ -7,75 +90,106 @@ - 执行向量相似度搜索 - 通过内置测试流程验证调用链 +### 功能特性 + +- **双模式运行** + - 实际连接模式：连接真实的 Milvus 服务器执行操作 + - 模拟测试模式：无需 Milvus 实例，验证调用链和参数 + +- **完整的向量数据库操作** + - 集合的创建、删除和重建 + - 向量索引的创建（支持 Flat 索引类型） + - 批量数据插入 + - 向量相似度搜索（支持 L2 距离度量） + +- **清晰的架构设计** + - 分层架构：入口层、业务层、测试层 + - 依赖注入友好的设计 + - 完善的 XML 文档注释 + ### 模块划分 + - **App（入口层）**：`Program.cs` - 提供交互式入口：输入 1=实际连接 Milvus 执行；输入 2=运行内置测试（无需 Milvus 实例）。 + - **Core/Service（业务层）**：`MilvusService.cs` - 封装与 Milvus 的连接、集合初始化、索引创建/加载、数据插入与搜索。 + - **Test Harness（测试层）**：`TestRunner.cs`、`MilvusServiceTests.cs` - `TestRunner` 负责编排测试流程；`MilvusServiceTests` 提供无外部依赖的模拟测试（验证调用链与参数）。 -### 环境要求 -- .NET SDK 9.0+ -- 仅当选择“实际运行（选项 1）”时需要：可访问的 Milvus Server（默认 `localhost:19530`）。 +### 运行示例 -### 快速开始 -1. 构建 - ```powershell - dotnet build - ``` -2. 运行（测试模式，无需 Milvus） - - PowerShell： - ```powershell - echo 2 | dotnet run - ``` - - Bash： - ```bash - echo 2 | dotnet run - ``` -3. 运行（实际连接 Milvus） - - 确保本地或可达的 Milvus 实例运行在 `localhost:19530`。 - - 程序启动后输入 `1`。 - -### 在解决方案根目录运行（多项目） -本仓库包含多个示例项目。可在解决方案根目录使用 `--project` 指定要运行的项目： +#### 1. 测试模式（无需 Milvus） ```powershell -# 运行 Milvus 示例（默认交互菜单 1/2） -dotnet run --project MilvusDemo +# PowerShell +echo 2 | dotnet run --project MilvusDemo -# 运行语音到函数示例 -dotnet run --project VoiceToFunctionDemo +# Bash +echo 2 | dotnet run --project MilvusDemo ``` -### 启动 Milvus（可选） -若需在本机快速启动 Milvus，可参考官方快速开始，或使用 Docker（示例）： +**预期输出：** +``` +开始运行MilvusService测试... +测试完成！ +``` -```bash -# 仅供参考，建议按官方文档选择合适的版本与持久化配置 -docker pull milvusdb/milvus:latest +#### 2. 实际连接模式（需要 Milvus） + +```powershell +# 启动 Milvus（如果未运行） docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest + +# 运行程序 +dotnet run --project MilvusDemo +# 然后输入 1 ``` -文档：`https://milvus.io/docs`（查看“Get Started / Install”）。 +**预期输出：** +``` +Milvus 演示程序 +1. 运行实际的 Milvus 操作 +2. 运行模拟测试 +请选择 (1/2): 1 +Collection 'csharp_demo_collection' dropped. +Collection 'csharp_demo_collection' created. +Index created. +Collection loaded. +Data inserted. -### 主要参数（实际运行模式） -- 主机与端口：`localhost:19530` +Search results: +- ID: 123 +- ID: 456 +... +``` + +### API 说明 + +#### MilvusService 类 + +**构造函数** +```csharp +public MilvusService(string host, int port, string collectionName, int dim) +``` + +**主要方法** + +| 方法 | 说明 | 参数 | +|------|------|------| +| `InitializeCollectionAsync()` | 初始化集合，存在则删除重建 | 无 | +| `CreateIndexAndLoadAsync()` | 创建索引并加载集合 | 无 | +| `InsertRandomDataAsync(int count)` | 插入指定数量的随机向量 | count: 向量数量 | +| `SearchVectorAsync(int topK)` | 执行向量相似度搜索 | topK: 返回结果数量 | + +**默认配置** +- 主机：`localhost` +- 端口：`19530` - 集合名：`csharp_demo_collection` - 向量维度：`8` - -> 提示：若需修改连接地址或集合名，请在代码中相应位置调整（例如在连接初始化与集合定义处）。 - -### 文件说明 -- `Program.cs`：控制台入口与菜单；调用服务或测试。 -- `MilvusService.cs`：核心服务，封装 Milvus 客户端操作。 -- `MilvusServiceTests.cs`：简单的模拟测试实现（不依赖 Milvus）。 -- `TestRunner.cs`：运行测试流程的编排类。 -- `MilvusDemo.csproj`：项目与依赖定义（包含 `Milvus.Client`）。 - -### 项目结构 -- `MilvusDemo/`：Milvus 向量数据库最小示例，支持实际连接与模拟测试两种模式。 -- `VoiceToFunctionDemo/`：语音（文本）解析为函数调用的示例，展示如何从自然语言中抽取参数并调用预定义函数。 +- 索引类型：`Flat` +- 相似度度量：`L2` --- @@ -86,24 +200,228 @@ docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest - `FILTER(List, Func)`：按条件筛选用户（支持年龄阈值与姓名包含） - `COUNTIF(double[], Func)`：按范围统计数量 -### 运行 +### 功能特性 + +- **自然语言解析** + - 支持中文指令识别 + - 同义词匹配机制 + - 灵活的参数提取 + +- **类型安全** + - 参数类型验证 + - 编译时类型检查 + - 运行时类型匹配 + +- **可扩展架构** + - 函数库动态注册 + - 支持自定义函数 + - 参数解析器可定制 + +### 内置函数 + +| 函数名 | 描述 | 参数类型 | 示例指令 | +|--------|------|----------|----------| +| `PRODUCT` | 计算多列对应行的乘积 | `double[]`, `double[]` | "计算C列和D列的乘积，C列是[1,3,5]，D列是[2,4,6]" | +| `FILTER` | 筛选满足条件的数据 | `List`, `Func` | "筛选出年龄大于28且姓名包含'李'的用户" | +| `COUNTIF` | 统计满足条件的记录数 | `double[]`, `Func` | "统计销售额在5000到20000之间的订单数" | + +### 运行示例 + ```powershell dotnet run --project VoiceToFunctionDemo ``` -程序内置了示例输入，启动后会依次演示： -- 计算两列数值的乘积（如 `[1,3,5]` 与 `[2,4,6]`） -- 筛选年龄大于某值且姓名包含关键字的用户 -- 统计销售额处于指定区间内的订单数 +**预期输出：** +``` +=== 语音指令：计算C列和D列的乘积，C列是[1,3,5]，D列是[2,4,6] === +匹配函数：PRODUCT +执行结果：2, 12, 30 -如需扩展，请修改 `VoiceToFunctionDemo/Program.cs`： -- 新增函数：在 `functionLibrary` 中增加 `FunctionInfo`，定义参数类型与执行逻辑。 -- 扩展解析：在 `ParseVoiceCommand` 中为新函数添加参数解析与类型校验。 +=== 语音指令：筛选出年龄大于28且姓名包含'李'的用户 === +匹配函数：FILTER +执行结果：李四(30), 李白(29) + +=== 语音指令：统计销售额在5000到20000之间的订单数，数据是[3000, 8000, 15000, 25000] === +匹配函数：COUNTIF +执行结果：2 +``` + +### 扩展开发 + +#### 添加新函数 + +1. 在 `Program.cs` 的 `functionLibrary` 中添加新的 `FunctionInfo`： + +```csharp +new FunctionInfo +{ + Name = "SUM", + Description = "计算数组的和", + Synonyms = new List { "求和", "总和", "合计" }, + MinParams = 1, + ParamTypes = new List { typeof(double[]) }, + Execute = (args) => + { + double[] data = (double[])args[0]; + return data.Sum(); + } +} +``` + +2. 在 `ParseVoiceCommand` 方法中添加参数解析逻辑： + +```csharp +case "SUM": + var sumData = Regex.Match(text, @"\[([\d, ]+)\]") + .Groups[1].Value.Split(',').Select(double.Parse).ToArray(); + result.Parameters = new object[] { sumData }; + result.ParamTypes = new[] { "Double[]" }; + break; +``` --- -### 常见问题（FAQ） -- 无法连接到 Milvus：请确认 Milvus 是否已启动并监听 `19530` 端口，以及本机/容器网络连通性。 -- 还原/编译失败：请确认已安装 .NET 9 SDK，并允许联网下载 NuGet 依赖；必要时执行 `dotnet restore` 后再构建。 -- 端口占用：如 `19530` 已被占用，请修改容器映射或程序连接端口并保持一致。 +## 开发指南 +### 在解决方案根目录运行 + +本仓库包含多个示例项目。可在解决方案根目录使用 `--project` 指定要运行的项目： + +```powershell +# 运行 Milvus 示例（默认交互菜单 1/2） +dotnet run --project MilvusDemo + +# 运行语音到函数示例 +dotnet run --project VoiceToFunctionDemo + +# 构建整个解决方案 +dotnet build +``` + +### 启动 Milvus（可选） + +若需在本机快速启动 Milvus，可参考官方快速开始，或使用 Docker： + +```bash +# 拉取最新镜像 +docker pull milvusdb/milvus:latest + +# 启动独立实例 +docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest + +# 查看日志 +docker logs -f milvus-standalone + +# 停止并删除容器 +docker stop milvus-standalone +docker rm milvus-standalone +``` + +**官方文档**：[https://milvus.io/docs](https://milvus.io/docs)（查看"Get Started / Install"） + +### 代码规范 + +- 遵循 C# 编码规范 +- 使用 XML 文档注释 +- 方法名使用 PascalCase +- 私有字段使用 _camelCase +- 异步方法以 Async 后缀结尾 + +### 测试 + +```powershell +# 运行 MilvusDemo 模拟测试 +echo 2 | dotnet run --project MilvusDemo + +# 运行 VoiceToFunctionDemo（内置测试） +dotnet run --project VoiceToFunctionDemo +``` + +--- + +## 常见问题（FAQ） + +### Milvus 相关 + +**Q: 无法连接到 Milvus？** + +A: 请确认： +- Milvus 是否已启动并监听 `19530` 端口 +- 使用 `docker ps` 检查容器状态 +- 使用 `docker logs milvus-standalone` 查看日志 +- 确认本机/容器网络连通性 + +**Q: 端口 19530 已被占用？** + +A: 修改容器映射或程序连接端口并保持一致： +```bash +# 使用其他端口 +docker run -d --name milvus-standalone -p 19531:19530 milvusdb/milvus:latest +``` + +### 构建相关 + +**Q: 还原/编译失败？** + +A: 请确认： +- 已安装 .NET 9 SDK：`dotnet --version` +- 允许联网下载 NuGet 依赖 +- 必要时执行 `dotnet restore` 后再构建 + +**Q: 如何清理构建产物？** + +A: +```powershell +dotnet clean +``` + +### VoiceToFunctionDemo 相关 + +**Q: 如何添加新的函数？** + +A: 参考 [扩展开发](#扩展开发) 部分，主要步骤： +1. 在 `functionLibrary` 中添加函数定义 +2. 在 `ParseVoiceCommand` 中添加参数解析逻辑 +3. 确保参数类型匹配 + +**Q: 支持英文指令吗？** + +A: 当前版本主要支持中文指令，如需支持英文，请在 `Synonyms` 中添加英文同义词。 + +--- + +## 贡献指南 + +欢迎贡献代码！请遵循以下步骤： + +1. Fork 本仓库 +2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) +3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) +4. 推送到分支 (`git push origin feature/AmazingFeature`) +5. 开启 Pull Request + +### 提交规范 + +- feat: 新功能 +- fix: 修复 bug +- docs: 文档更新 +- style: 代码格式调整 +- refactor: 重构 +- test: 测试相关 +- chore: 构建/工具相关 + +--- + +## 许可证 + +本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。 + +## 联系方式 + +如有问题或建议，请通过以下方式联系： +- 提交 Issue +- 发起 Pull Request + +--- + +**最后更新**: 2026-02-26