docs(api): rewrite markdown to match current routes
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 + 字段说明)。
This commit is contained in:
+22
-15
@@ -2,22 +2,26 @@
|
||||
|
||||
[返回目录](./README.md)
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
| ---- | ------------- | --------------------- |
|
||||
| GET | `/evaluation` | 获取评估任务 |
|
||||
| POST | `/evaluation` | 创建评估任务 |
|
||||
| 方法 | 路径 | 描述 |
|
||||
| ---- | -------------- | --------------------- |
|
||||
| GET | `/evaluation/` | 获取评估任务结果 |
|
||||
| POST | `/evaluation/` | 创建评估任务 |
|
||||
|
||||
## GET `/evaluation` - 获取评估任务
|
||||
> 注:服务端路由带尾斜杠(Gin 会自动从 `/evaluation` 重定向到 `/evaluation/`),下方示例为方便阅读用了 `/evaluation`。
|
||||
|
||||
**请求参数**:
|
||||
- `task_id`: 从 `POST /evaluation` 接口中获取到的任务 ID
|
||||
- `X-API-Key`: 用户 API Key
|
||||
## 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-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
@@ -88,17 +92,20 @@ curl --location 'http://localhost:8080/api/v1/evaluation?task_id=c34563ad-b09f-4
|
||||
|
||||
## POST `/evaluation` - 创建评估任务
|
||||
|
||||
**请求参数**:
|
||||
- `dataset_id`: 评估使用的数据集,暂时只支持官方测试数据集 `default`
|
||||
- `knowledge_base_id`: 评估使用的知识库
|
||||
- `chat_id`: 评估使用的对话模型
|
||||
- `rerank_id`: 评估使用的重排序模型
|
||||
**参数说明(请求体)**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | ----------------------------------------------- |
|
||||
| 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-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"dataset_id": "default",
|
||||
|
||||
Reference in New Issue
Block a user