mirror of https://github.com/Tencent/WeKnora.git synced 2026-06-04 13:30:32 +08:00

Files

nullkey 1c7171b2c6 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 + 字段说明）。

2026-05-12 13:16:58 +08:00

5.4 KiB

Raw Permalink Blame History

评估功能 API

返回目录

方法	路径	描述
GET	`/evaluation/`	获取评估任务结果
POST	`/evaluation/`	创建评估任务

注：服务端路由带尾斜杠（Gin 会自动从 /evaluation 重定向到 /evaluation/），下方示例为方便阅读用了 /evaluation。

GET `/evaluation` - 获取评估任务结果

参数说明（查询参数）:

字段	类型	必填	说明
task_id	string	是	从 `POST /evaluation` 返回的任务 ID

请求:

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'

响应:

{
    "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

请求:

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"
}'

响应:

{
    "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
}

5.4 KiB Raw Permalink Blame History Unescape Escape

评估功能 API

GET /evaluation - 获取评估任务结果

POST /evaluation - 创建评估任务

5.4 KiB

Raw Permalink Blame History

GET `/evaluation` - 获取评估任务结果

POST `/evaluation` - 创建评估任务