# 火山方舟知识库接入指南

## 概述

本项目已成功接入火山方舟知识库，支持从火山方舟知识库中检索相关内容作为 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 中的参考实现