# 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