bigwo/realtime_dialog_external_rag_test/java/VOLC_KNOWLEDGE_INTEGRATION.md

火山方舟知识库接入指南

概述

本项目已成功接入火山方舟知识库，支持从火山方舟知识库中检索相关内容作为 external_rag 注入到实时对话系统中。

功能特性

• 支持从火山方舟知识库智能检索相关内容
• 多级降级策略：火山方舟 → test2/server → 本地知识库
• 支持配置相似度阈值和返回结果数量
• 完整的错误处理和日志记录
• 与test2项目配置完全兼容

配置方式

方式一：通过 .env 文件配置（推荐）

1. 复制 .env.example 文件为 .env（或直接在 test2/server/.env 中配置）

2. 配置以下参数：

# 启用火山方舟知识库
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

方式二：通过命令行参数配置

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. 运行测试

   # 文本模式
   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 中的参考实现