137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
|
# 火山方舟知识库接入指南
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
本项目已成功接入火山方舟知识库，支持从火山方舟知识库中检索相关内容作为 external_rag 注入到实时对话系统中。
|
|||
|
|
|
|||
|
|
## 功能特性
|
|||
|
|
|
|||
|
|
- 支持从火山方舟知识库智能检索相关内容
|
|||
|
|
- 多级降级策略：火山方舟 → test2/server → 本地知识库
|
|||
|
|
- 支持配置相似度阈值和返回结果数量
|
|||
|
|
- 完整的错误处理和日志记录
|
|||
|
|
- 与test2项目配置完全兼容
|
|||
|
|
|
|||
|
|
## 配置方式
|
|||
|
|
|
|||
|
|
### 方式一：通过 .env 文件配置（推荐）
|
|||
|
|
|
|||
|
|
1. 复制 `.env.example` 文件为 `.env`（或直接在 `test2/server/.env` 中配置）
|
|||
|
|
|
|||
|
|
2. 配置以下参数：
|
|||
|
|
|
|||
|
|
```env
|
|||
|
|
# 启用火山方舟知识库
|
|||
|
|
VOLC_ARK_ENABLED=true
|
|||
|
|
|
|||
|
|
# 火山方舟 API Key（可选，如果未设置则使用VOLC_ACCESS_KEY_ID）
|
|||
|
|
VOLC_ARK_API_KEY=your_ark_api_key
|
|||
|
|
|
|||
|
|
# 火山方舟 Endpoint ID
|
|||
|
|
VOLC_ARK_ENDPOINT_ID=your_ark_endpoint_id
|
|||
|
|
|
|||
|
|
# 火山方舟知识库数据集ID（多个用逗号分隔）
|
|||
|
|
VOLC_ARK_KNOWLEDGE_BASE_IDS=your_knowledge_base_dataset_id
|
|||
|
|
|
|||
|
|
# 检索参数（可选）
|
|||
|
|
VOLC_ARK_KNOWLEDGE_TOP_K=3
|
|||
|
|
VOLC_ARK_KNOWLEDGE_THRESHOLD=0.5
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 方式二：通过命令行参数配置
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mvn exec:java -Dexec.args="--mod=text --volc-enabled --volc-endpoint=your_endpoint --volc-kb-ids=your_kb_ids --volc-api-key=your_api_key --volc-topk=5 --volc-threshold=0.6"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 命令行参数说明
|
|||
|
|
|
|||
|
|
| 参数 | 说明 | 必填 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `--volc-enabled` | 启用火山方舟知识库 | 是 |
|
|||
|
|
| `--volc-ak` | 火山云 Access Key ID | 否 |
|
|||
|
|
| `--volc-sk` | 火山云 Secret Access Key | 否 |
|
|||
|
|
| `--volc-api-key` | 火山方舟 API Key | 否 |
|
|||
|
|
| `--volc-endpoint` | 火山方舟 Endpoint ID | 是 |
|
|||
|
|
| `--volc-kb-ids` | 火山方舟知识库数据集ID，多个用逗号分隔 | 是 |
|
|||
|
|
| `--volc-topk` | 返回结果数量，默认3 | 否 |
|
|||
|
|
| `--volc-threshold` | 相似度阈值，默认0.5 | 否 |
|
|||
|
|
|
|||
|
|
## 使用流程
|
|||
|
|
|
|||
|
|
1. **准备火山方舟知识库**
|
|||
|
|
- 在火山引擎方舟控制台创建知识库
|
|||
|
|
- 上传文档并确保文档已正确索引
|
|||
|
|
- 记录知识库 Dataset ID
|
|||
|
|
|
|||
|
|
2. **配置参数**
|
|||
|
|
- 通过 .env 文件或命令行参数配置访问密钥和数据集信息
|
|||
|
|
|
|||
|
|
3. **运行测试**
|
|||
|
|
```bash
|
|||
|
|
# 文本模式
|
|||
|
|
mvn exec:java -Dexec.args="--mod=text --volc-enabled"
|
|||
|
|
|
|||
|
|
# 麦克风模式
|
|||
|
|
mvn exec:java -Dexec.args="--volc-enabled"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
4. **验证结果**
|
|||
|
|
- 查看控制台日志，确认火山方舟知识库检索是否成功
|
|||
|
|
- 确认返回的 external_rag 内容是否符合预期
|
|||
|
|
|
|||
|
|
## 降级策略
|
|||
|
|
|
|||
|
|
系统采用多级降级策略，确保在任何情况下都能正常工作：
|
|||
|
|
|
|||
|
|
1. **第一优先级**：火山方舟知识库（如果启用）
|
|||
|
|
2. **第二优先级**：test2/server 知识库
|
|||
|
|
3. **第三优先级**：本地 sample_rag.json 文件
|
|||
|
|
|
|||
|
|
## 文件变更说明
|
|||
|
|
|
|||
|
|
### 新增文件
|
|||
|
|
|
|||
|
|
- `VolcKnowledgeClient.java` - 火山方舟知识库客户端
|
|||
|
|
- `.env.example` - 配置示例文件（已更新为火山方舟配置）
|
|||
|
|
- `VOLC_KNOWLEDGE_INTEGRATION.md` - 本说明文档
|
|||
|
|
|
|||
|
|
### 修改文件
|
|||
|
|
|
|||
|
|
- `pom.xml` - 添加HTTP客户端依赖（已移除VikingDB SDK）
|
|||
|
|
- `Config.java` - 添加火山方舟配置项
|
|||
|
|
- `Main.java` - 添加火山方舟命令行参数
|
|||
|
|
- `ServerResponseHandler.java` - 集成火山方舟知识库检索
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **权限安全**：请妥善保管 Access Key 和 API Key，不要提交到代码仓库
|
|||
|
|
2. **网络访问**：确保服务器可以访问火山方舟 API（ark.cn-beijing.volces.com）
|
|||
|
|
3. **知识库准备**：确保知识库已正确创建并包含索引数据
|
|||
|
|
4. **性能优化**：根据实际需求调整 top_k 和 threshold 参数
|
|||
|
|
5. **向后兼容**：保留了对旧配置项的兼容支持（VOLC_KNOWLEDGE_*）
|
|||
|
|
|
|||
|
|
## 故障排查
|
|||
|
|
|
|||
|
|
### 问题：火山方舟知识库检索失败
|
|||
|
|
|
|||
|
|
**解决方案**：
|
|||
|
|
1. 检查 Endpoint ID 和 数据集ID 是否正确
|
|||
|
|
2. 确认 API Key 或 Access Key 是否正确
|
|||
|
|
3. 查看网络连接是否正常
|
|||
|
|
4. 检查控制台错误日志
|
|||
|
|
|
|||
|
|
### 问题：检索结果不相关
|
|||
|
|
|
|||
|
|
**解决方案**：
|
|||
|
|
1. 调整 threshold 参数（降低值可以返回更多结果）
|
|||
|
|
2. 增加 top_k 参数获取更多候选结果
|
|||
|
|
3. 检查知识库中的文档内容是否相关
|
|||
|
|
|
|||
|
|
## 技术支持
|
|||
|
|
|
|||
|
|
如遇问题，请查看：
|
|||
|
|
- 火山方舟官方文档：https://www.volcengine.com/docs/84313
|
|||
|
|
- 项目控制台日志输出
|
|||
|
|
- test2/server/services/toolExecutor.js 中的参考实现
|