mirror of
https://github.com/Tencent/WeKnora.git
synced 2026-06-04 13:30:32 +08:00
1c7171b2c6
Refs #890 #1049 #1168. 按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go 对齐。每个端点新增参数说明小节（path/query/body 字段含义）和响应字段 含义说明（#1168 的核心诉求）。 【与代码对齐】 - 删除已下线端点：system.md 中的 /system/minio/buckets（代码中已无对 应路由）。 - 修正路径错误：chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id； /chunks/:id/delete-question → /chunks/by-id/:id/questions； organization.md 中 /organizations/preview/:invite_code → :code。 - 修正字段类型：faq tag_id / entry_id 由 string 改为 int64； knowledge.search 响应结构纠正。 - 补齐缺失端点（move-targets、batch-delete、move/progress、pin/unpin/ stop/continue-stream、tool-approvals、organization agent-shares 等 30+ 条）。 【精简】 - knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例 收敛为指向首次出现（"字段结构同 POST /xxx 响应"），节省约 400 行 而不损失信息（仅去重，原作者写的每个字段定义都保留可达）。 - 示例 X-API-Key 统一为 sk-xxxxx（避免读者复制看似真实的 key）。 【清理】 - 删除内部实现细节引用：mcp-service.md 中 6 处 "issue #1173"、 organization.md 中 "RegisterOrganizationRoutes" 等。 不动 initialization.md：其中端点（KB 配置、模型连通性测试、Ollama 管理） 对集成方有实用价值，保留原作者写好的内容不删。 格式统一遵循 web-search.md 重写后的范式（路由表 + 每端点方法/路径 + 参数表 + curl + 响应 JSON + 字段说明）。
162 lines
5.4 KiB
Markdown
162 lines
5.4 KiB
Markdown
# 评估功能 API
|
||
|
||
[返回目录](./README.md)
|
||
|
||
| 方法 | 路径 | 描述 |
|
||
| ---- | -------------- | --------------------- |
|
||
| GET | `/evaluation/` | 获取评估任务结果 |
|
||
| POST | `/evaluation/` | 创建评估任务 |
|
||
|
||
> 注：服务端路由带尾斜杠（Gin 会自动从 `/evaluation` 重定向到 `/evaluation/`），下方示例为方便阅读用了 `/evaluation`。
|
||
|
||
## GET `/evaluation` - 获取评估任务结果
|
||
|
||
**参数说明（查询参数）**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| -------- | ------ | ---- | --------------------------------------------------- |
|
||
| task_id | string | 是 | 从 `POST /evaluation` 返回的任务 ID |
|
||
|
||
**请求**:
|
||
|
||
```bash
|
||
curl --location 'http://localhost:8080/api/v1/evaluation?task_id=c34563ad-b09f-4858-b72e-e92beb80becb' \
|
||
--header 'X-API-Key: sk-xxxxx' \
|
||
--header 'Content-Type: application/json'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"task": {
|
||
"id": "c34563ad-b09f-4858-b72e-e92beb80becb",
|
||
"tenant_id": 1,
|
||
"dataset_id": "default",
|
||
"start_time": "2025-08-12T14:54:26.221804768+08:00",
|
||
"status": 2,
|
||
"total": 1,
|
||
"finished": 1
|
||
},
|
||
"params": {
|
||
"session_id": "",
|
||
"knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc",
|
||
"vector_threshold": 0.5,
|
||
"keyword_threshold": 0.3,
|
||
"embedding_top_k": 10,
|
||
"vector_database": "",
|
||
"rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0",
|
||
"rerank_top_k": 5,
|
||
"rerank_threshold": 0.7,
|
||
"chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
|
||
"summary_config": {
|
||
"max_tokens": 0,
|
||
"repeat_penalty": 1,
|
||
"top_k": 0,
|
||
"top_p": 0,
|
||
"frequency_penalty": 0,
|
||
"presence_penalty": 0,
|
||
"prompt": "这是用户和助手之间的对话。",
|
||
"context_template": "你是一个专业的智能信息检索助手",
|
||
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
|
||
"temperature": 0.3,
|
||
"seed": 0,
|
||
"max_completion_tokens": 2048
|
||
},
|
||
"fallback_strategy": "",
|
||
"fallback_response": "抱歉，我无法回答这个问题。"
|
||
},
|
||
"metric": {
|
||
"retrieval_metrics": {
|
||
"precision": 0,
|
||
"recall": 0,
|
||
"ndcg3": 0,
|
||
"ndcg10": 0,
|
||
"mrr": 0,
|
||
"map": 0
|
||
},
|
||
"generation_metrics": {
|
||
"bleu1": 0.037656734016532384,
|
||
"bleu2": 0.04067392145167686,
|
||
"bleu4": 0.048963321289052536,
|
||
"rouge1": 0,
|
||
"rouge2": 0,
|
||
"rougel": 0
|
||
}
|
||
}
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
## POST `/evaluation` - 创建评估任务
|
||
|
||
**参数说明（请求体）**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| ----------------- | ------ | ---- | ----------------------------------------------- |
|
||
| dataset_id | string | 是 | 评估数据集，目前仅支持 `default`（官方测试集） |
|
||
| knowledge_base_id | string | 是 | 评估使用的知识库 ID |
|
||
| chat_id | string | 是 | 评估使用的对话模型 ID |
|
||
| rerank_id | string | 是 | 评估使用的重排序模型 ID |
|
||
|
||
**请求**:
|
||
|
||
```bash
|
||
curl --location 'http://localhost:8080/api/v1/evaluation' \
|
||
--header 'X-API-Key: sk-xxxxx' \
|
||
--header 'Content-Type: application/json' \
|
||
--data '{
|
||
"dataset_id": "default",
|
||
"knowledge_base_id": "kb-00000001",
|
||
"chat_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
|
||
"rerank_id": "b30171a1-787b-426e-a293-735cd5ac16c0"
|
||
}'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"task": {
|
||
"id": "c34563ad-b09f-4858-b72e-e92beb80becb",
|
||
"tenant_id": 1,
|
||
"dataset_id": "default",
|
||
"start_time": "2025-08-12T14:54:26.221804768+08:00",
|
||
"status": 1
|
||
},
|
||
"params": {
|
||
"session_id": "",
|
||
"knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc",
|
||
"vector_threshold": 0.5,
|
||
"keyword_threshold": 0.3,
|
||
"embedding_top_k": 10,
|
||
"vector_database": "",
|
||
"rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0",
|
||
"rerank_top_k": 5,
|
||
"rerank_threshold": 0.7,
|
||
"chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
|
||
"summary_config": {
|
||
"max_tokens": 0,
|
||
"repeat_penalty": 1,
|
||
"top_k": 0,
|
||
"top_p": 0,
|
||
"frequency_penalty": 0,
|
||
"presence_penalty": 0,
|
||
"prompt": "这是用户和助手之间的对话。",
|
||
"context_template": "你是一个专业的智能信息检索助手，xxx",
|
||
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
|
||
"temperature": 0.3,
|
||
"seed": 0,
|
||
"max_completion_tokens": 2048
|
||
},
|
||
"fallback_strategy": "",
|
||
"fallback_response": "抱歉，我无法回答这个问题。"
|
||
}
|
||
},
|
||
"success": true
|
||
}
|
||
```
|