vecml-rag-api-test

v0.0.1-beta.1

Published

2 months ago

VecML RAG API测试工具

0High
0Medium
0Low

maonianyou

vecml rag api test vector retrieval embedding

VecML RAG API 测试工具

一个专业的VecML RAG API测试工具，提供完整的文档索引、检索测试和性能评估功能。支持多种测试模式、灵活的配置管理和详细的可视化报告。

🚀 功能特性

🔧 多模式测试: 支持索引测试、检索测试和完整测试三种模式
📊 性能评估: 详细的索引性能和检索准确率分析
📈 双重报告: 统一报告和分离式报告两种生成方式
⚡ 并发控制: 可配置的并发测试，提高测试效率
🎯 精准配置: 支持多层级配置管理和交互式配置
📋 详细统计: 提供完整的测试统计和性能分析
🛠️ CLI工具: 友好的命令行界面，支持多种操作模式
🔄 Pipeline管理: 自动Pipeline创建和清理功能
📁 文件管理: 支持多种文件格式和批量处理

📦 安装

全局安装（推荐）

# 全局安装 vecml-test 工具
npm install -g vecml-rag-api-test

# 安装完成后即可在任何目录使用
vecml-test --help

本地安装

# 在项目目录中本地安装
npm install vecml-rag-api-test

# 使用 npx 运行（无需全局安装）
npx vecml-rag-api-test --help

🎯 快速开始

1. 初始化配置

# 创建默认配置文件
npx vecml-test init

# 或指定配置文件路径
npx vecml-test init -o ./my-config.json

2. 交互式配置

# 启动交互式配置工具
npx vecml-test config

3. 运行测试

# 运行完整测试（推荐）
npx vecml-test full

# 仅运行索引测试
npx vecml-test index

# 仅运行检索测试
npx vecml-test retrieval

📋 命令详解

核心测试命令

`index` - 索引测试

# 基础索引测试
npx vecml-test index

# 指定配置文件
npx vecml-test index -c ./config.json

# 指定测试文件目录
npx vecml-test index -d ./test-files

# 指定服务器地址
npx vecml-test index -s http://localhost:40004

# 设置并发数和测试轮次
npx vecml-test index --concurrency 5 --cycles 3

`retrieval` - 检索测试

# 基础检索测试（自动选择最新的Pipeline）
npx vecml-test retrieval

# 指定特定的Pipeline进行检索测试
npx vecml-test retrieval -p test_pipeline_20251215_1430_01

# 自定义配置
npx vecml-test retrieval -c ./config.json -o ./reports

# 组合使用：指定Pipeline和配置文件
npx vecml-test retrieval -p test_pipeline_20251215_1430_01 -c ./config.json

`full` - 完整测试

# 运行完整测试流程（索引+检索）
npx vecml-test full

# 完整测试的所有选项
npx vecml-test full -c ./config.json -d ./test-files -s http://localhost:40004 -o ./reports --cycles 3 --concurrency 4

管理命令

`init` - 初始化配置

# 创建默认配置文件
npx vecml-test init

# 指定输出路径
npx vecml-test init -o ./custom-config.json

`config` - 交互式配置

# 启动配置向导
npx vecml-test config

`report` - 查看报告

# 查看最新报告
npx vecml-test report

# 查看指定报告
npx vecml-test report -p ./test-reports/2024-12-01/report.html

`list` - 列出Pipeline

# 列出所有可用的Pipeline
npx vecml-test list

`delete` - 删除Pipeline

# 删除指定的Pipeline
npx vecml-test delete -p test_pipeline_20251215_1430_01

# 或使用完整参数名
npx vecml-test delete --pipeline test_pipeline_20251215_1430_01

`clean` - 清理文件

# 清理所有测试报告和临时文件
npx vecml-test clean

# 仅清理报告文件
npx vecml-test clean --reports-only

# 仅清理临时文件
npx vecml-test clean --temp-only

⚙️ 配置文件说明

完整配置示例

{
  "apiServer": "http://localhost:40004",
  "ragSdkPath": "/path/to/rag_sdk_server/bin",// eg. "/home/jp/workspace/rag_sdk_server/bin",
  "testFilesDir": "./test-files",
  "concurrency": 4,
  "enableConcurrencyControl": true,
  "testCycles": 3,
  "timeoutMs": 1800000,
  "retrievalTestQueries": [
    "what's the key idea of this doc?",
    "summarize the main content",
    "what are the key points?"
  ],
  "outputDir": "./test-reports",
  "supportedFileTypes": [".txt", ".pdf", ".docx", ".doc", ".md", ".xlsx"],
  "retrievalSettings": {
    "topK": 5,
    "scoreThreshold": 0.7,
    "enableRelevanceAssessment": true,
    "timingTestRounds": 3
  },
  "reportSettings": {
    "generateSeparateReports": true,
    "includeDetailedLogs": true,
    "autoOpenReport": false,
    "reportFormat": "html"
  },
  "pipelineSettings": {
    "autoCleanup": false,
    "maxPipelinesPerDay": 10,
    "retentionDays": 7
  }
}

配置参数详解

基础配置

| 参数 | 说明 | 默认值 | 类型 | |------|------|--------|------| | apiServer | VecML API服务器地址 | http://localhost:40004 | string | | ragSdkPath | RAG SDK服务器bin目录路径 | /path/to/rag_sdk_server/bin | string | | testFilesDir | 测试文件目录 | ./test-files | string | | concurrency | 并发测试数量 | 4 | number | | enableConcurrencyControl | 启用并发控制 | true | boolean | | testCycles | 测试循环次数 | 3 | number | | timeoutMs | 请求超时时间（毫秒） | 1800000 | number | | outputDir | 测试报告输出目录 | ./test-reports | string |

检索设置 (retrievalSettings)

| 参数 | 说明 | 默认值 | 类型 | |------|------|--------|------| | topK | 返回结果数量 | 5 | number | | scoreThreshold | 相关性分数阈值 | 0.7 | number | | enableRelevanceAssessment | 启用相关性评估 | true | boolean | | timingTestRounds | 时间测试轮次 | 3 | number |

报告设置 (reportSettings)

| 参数 | 说明 | 默认值 | 类型 | |------|------|--------|------| | generateSeparateReports | 生成分离式报告 | true | boolean | | includeDetailedLogs | 包含详细日志 | true | boolean | | autoOpenReport | 自动打开报告 | false | boolean | | reportFormat | 报告格式 | html | string |

Pipeline设置 (pipelineSettings)

| 参数 | 说明 | 默认值 | 类型 | |------|------|--------|------| | autoCleanup | 自动清理Pipeline | false | boolean | | maxPipelinesPerDay | 每日最大Pipeline数 | 10 | number | | retentionDays | Pipeline保留天数 | 7 | number |

Pipeline命名规则

Pipeline名称采用标准化格式：test_pipeline_{yyyyMMdd_HHmm}_{cycle}

日期时间部分: yyyyMMdd_HHmm (年月日_时分)
循环编号: 两位数字，从01开始
示例: test_pipeline_20251215_1430_01

这种格式确保了：

✅ 时间精度到分钟级，避免同一天内的命名冲突
✅ 便于按时间排序和管理
✅ 支持同一时间点的多轮测试

📊 报告系统

报告类型

1. 统一报告 (report-generator.ts)

特点: 将所有测试结果整合到统一报告中
适用场景: 快速查看完整测试流程
报告类型:
- 索引测试报告
- 检索测试报告
- 完整测试报告

2. 分离式报告 (separated-report-generator.ts)

特点: 索引和检索测试分别生成独立报告
适用场景: 详细性能分析和质量评估
增强功能:
- 平均时间计算
- 精确度分析
- 相关性统计
- 增强的视觉效果

报告内容

概览统计

📈 文件总数和处理状态
⏱️ 平均索引/检索时间
🎯 成功率和失败率统计
📊 性能趋势分析

详细结果

📄 索引测试: 文件信息、处理时间、状态详情
🔍 检索测试: 查询结果、相关性分析、精确度计算
📋 性能分析: 时间分布、并发效果、瓶颈识别

🔧 测试流程

1. 文件准备

# 创建测试文件目录
mkdir test-files

# 添加测试文件（支持多种格式）
cp *.txt *.pdf *.docx *.md test-files/

2. 配置调优

# 使用交互式配置
npx vecml-test config

# 或手动编辑配置文件
vim vecml-test.json

3. 执行测试

# 推荐：运行完整测试
npx vecml-test full -c ./vecml-test.json

# 或分步执行
npx vecml-test index -c ./vecml-test.json
npx vecml-test retrieval -c ./vecml-test.json

# 分离测试场景：先索引后检索
npx vecml-test index                    # 创建新的知识库
npx vecml-test retrieval               # 自动选择最新的知识库

# 指定特定知识库进行检索
npx vecml-test retrieval -p test_pipeline_20251215_1430_01

4. 管理Pipeline

# 查看所有可用的Pipeline
npx vecml-test list

# 删除不需要的Pipeline
npx vecml-test delete -p test_pipeline_20251215_1430_01

# 清理测试文件和报告
npx vecml-test clean

5. 分析结果

# 查看测试报告
npx vecml-test report

# 或直接打开HTML报告文件
open ./test-reports/2024-12-01/report.html

📁 支持的文件类型

| 格式 | 扩展名 | 说明 | |------|--------|------| | 文本文件 | .txt | 纯文本文档 | | PDF文档 | .pdf | PDF格式文档 | | Word文档 | .docx, .doc | Microsoft Word文档 | | Markdown | .md | Markdown格式文档 | | Excel表格 | .xlsx | Microsoft Excel文档 |

🛠️ 故障排查

常见问题

1. API连接失败

# 检查服务状态
curl http://localhost:40004/health

# 测试连接
npx vecml-test index -s http://localhost:40004 --cycles 1

2. 文件处理失败

# 检查文件权限
ls -la test-files/

# 验证文件格式
file test-files/*

3. 测试超时

{
  "timeoutMs": 3600000,  // 增加到60分钟
  "concurrency": 2,       // 降低并发数
  "enableConcurrencyControl": true  // 启用并发控制（默认）
}

调试模式

# 启用详细日志
DEBUG=vecml-test:* npx vecml-test full

# 单文件测试
npx vecml-test index -d ./single-file --cycles 1

🔄 开发和扩展（仅开发者需要）

开发环境

如果你需要修改或贡献代码，才需要克隆项目：

# 克隆项目
git clone <repository-url>
cd vecml-test/tool

# 安装依赖
npm install
# 或使用 pnpm
pnpm install

# 构建项目
npm run build

项目结构

tool/
├── src/
│   ├── api/          # API接口封装
│   ├── core/         # 核心测试逻辑
│   ├── utils/        # 工具函数
│   ├── index.ts      # CLI入口
│   ├── types.ts      # 类型定义
│   ├── report-generator.ts         # 统一报告生成器
│   └── separated-report-generator.ts # 分离式报告生成器
├── config.json       # 默认配置
└── package.json

自定义扩展

1. 添加新文件类型

{
  "supportedFileTypes": [".txt", ".pdf", ".docx", ".pptx"]
}

2. 自定义查询语句

{
  "retrievalTestQueries": [
    "自定义查询1",
    "自定义查询2"
  ]
}

3. 扩展报告格式

修改 ReportGenerator 类
添加新的模板文件
扩展配置选项

📝 更新日志

v0.0.1-alpha-7 (2025-10-16)

v0.0.1-alpha-6 (2025-10-16)

v0.0.1-alpha-5 (2025-10-16)

v0.0.1-alpha-4 (2025-10-16)

v0.0.1-alpha-3 (2025-10-16)

v0.0.1-alpha-2 (2025-10-16)

v0.0.1-alpha-1 (2025-10-16)

✨ 重构CLI命令结构，支持多种测试模式
🔧 新增分离式报告生成器
⚙️ 完善配置管理系统
📊 增强性能分析功能
🛠️ 优化错误处理和日志输出
📁 支持更多文件格式
🔄 改进Pipeline管理机制
控制并发
修复版本号显示
更新说明文档
知识库管理功能
- 新增list命令列出所有Pipeline
- 新增delete命令删除指定Pipeline
- 新增clean命令清理所有测试文件和报告

v0.0.1-alpha.0 (2025-10-15)

✅ 初始版本发布
✅ 基础测试功能
✅ HTML报告生成
✅ 配置文件管理

📄 许可证

MIT License

🤝 贡献

欢迎提交Issue和Pull Request来改进这个工具！

注意: 确保VecML API服务正在运行，并且配置了正确的服务器地址。建议在生产环境使用前先进行小规模测试。