ShaoHua
428 lines
11 KiB
Markdown
428 lines
11 KiB
Markdown
# 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` 的极简示例项目，演示：
|
||
- 初始化集合（存在则删除并重建）
|
||
- 创建向量索引与加载集合
|
||
- 批量插入随机向量
|
||
- 执行向量相似度搜索
|
||
- 通过内置测试流程验证调用链
|
||
|
||
### 功能特性
|
||
|
||
- **双模式运行**
|
||
- 实际连接模式：连接真实的 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` 提供无外部依赖的模拟测试（验证调用链与参数）。
|
||
|
||
### 运行示例
|
||
|
||
#### 1. 测试模式（无需 Milvus）
|
||
|
||
```powershell
|
||
# PowerShell
|
||
echo 2 | dotnet run --project MilvusDemo
|
||
|
||
# Bash
|
||
echo 2 | dotnet run --project MilvusDemo
|
||
```
|
||
|
||
**预期输出：**
|
||
```
|
||
开始运行MilvusService测试...
|
||
测试完成！
|
||
```
|
||
|
||
#### 2. 实际连接模式（需要 Milvus）
|
||
|
||
```powershell
|
||
# 启动 Milvus（如果未运行）
|
||
docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest
|
||
|
||
# 运行程序
|
||
dotnet run --project MilvusDemo
|
||
# 然后输入 1
|
||
```
|
||
|
||
**预期输出：**
|
||
```
|
||
Milvus 演示程序
|
||
1. 运行实际的 Milvus 操作
|
||
2. 运行模拟测试
|
||
请选择 (1/2): 1
|
||
Collection 'csharp_demo_collection' dropped.
|
||
Collection 'csharp_demo_collection' created.
|
||
Index created.
|
||
Collection loaded.
|
||
Data inserted.
|
||
|
||
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`
|
||
- 索引类型：`Flat`
|
||
- 相似度度量：`L2`
|
||
|
||
---
|
||
|
||
## VoiceToFunctionDemo
|
||
|
||
一个将中文自然语言指令解析为函数调用的控制台示例。内置函数库包含：
|
||
- `PRODUCT(double[], double[])`：计算两列数值的逐项乘积
|
||
- `FILTER(List<User>, Func<User,bool>)`：按条件筛选用户（支持年龄阈值与姓名包含）
|
||
- `COUNTIF(double[], Func<double,bool>)`：按范围统计数量
|
||
|
||
### 功能特性
|
||
|
||
- **自然语言解析**
|
||
- 支持中文指令识别
|
||
- 同义词匹配机制
|
||
- 灵活的参数提取
|
||
|
||
- **类型安全**
|
||
- 参数类型验证
|
||
- 编译时类型检查
|
||
- 运行时类型匹配
|
||
|
||
- **可扩展架构**
|
||
- 函数库动态注册
|
||
- 支持自定义函数
|
||
- 参数解析器可定制
|
||
|
||
### 内置函数
|
||
|
||
| 函数名 | 描述 | 参数类型 | 示例指令 |
|
||
|--------|------|----------|----------|
|
||
| `PRODUCT` | 计算多列对应行的乘积 | `double[]`, `double[]` | "计算C列和D列的乘积，C列是[1,3,5]，D列是[2,4,6]" |
|
||
| `FILTER` | 筛选满足条件的数据 | `List<User>`, `Func<User,bool>` | "筛选出年龄大于28且姓名包含'李'的用户" |
|
||
| `COUNTIF` | 统计满足条件的记录数 | `double[]`, `Func<double,bool>` | "统计销售额在5000到20000之间的订单数" |
|
||
|
||
### 运行示例
|
||
|
||
```powershell
|
||
dotnet run --project VoiceToFunctionDemo
|
||
```
|
||
|
||
**预期输出：**
|
||
```
|
||
=== 语音指令：计算C列和D列的乘积，C列是[1,3,5]，D列是[2,4,6] ===
|
||
匹配函数：PRODUCT
|
||
执行结果：2, 12, 30
|
||
|
||
=== 语音指令：筛选出年龄大于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<string> { "求和", "总和", "合计" },
|
||
MinParams = 1,
|
||
ParamTypes = new List<Type> { 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;
|
||
```
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 在解决方案根目录运行
|
||
|
||
本仓库包含多个示例项目。可在解决方案根目录使用 `--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
|