opensource/WeKnora
3
0
Fork 0
mirror of https://github.com/Tencent/WeKnora.git synced 2026-08-31 00:50:02 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
daa9ef500c245e2406bdccf36fd29957ffc24338
WeKnora/docs/api/faq.md
T
wizardchen daa9ef500c feat: add agent management functionality 
- Introduced a new package for managing custom agents, including CRUD operations for agent creation, retrieval, updating, and deletion.
- Implemented API endpoints for listing agents and retrieving agent placeholders.
- Added data structures for agent configuration and requests, enhancing the overall agent management capabilities.
- Enhanced the client with methods to interact with the new agent management features, improving user experience in managing agents.

These changes significantly expand the application's functionality for handling custom agents, providing users with a comprehensive toolset for agent management.
2026-03-09 17:34:13 +08:00

15 KiB
Raw Blame History

FAQ管理 API

返回目录

方法 路径 描述
GET /knowledge-bases/:id/faq/entries 获取FAQ条目列表
POST /knowledge-bases/:id/faq/entries 批量导入FAQ条目
POST /knowledge-bases/:id/faq/entry 创建单个FAQ条目
GET /knowledge-bases/:id/faq/entries/:entry_id 获取单个FAQ条目
PUT /knowledge-bases/:id/faq/entries/:entry_id 更新单个FAQ条目
POST /knowledge-bases/:id/faq/entries/:entry_id/similar-questions 添加相似问题
PUT /knowledge-bases/:id/faq/entries/fields 批量更新FAQ字段
PUT /knowledge-bases/:id/faq/entries/tags 批量更新FAQ标签
DELETE /knowledge-bases/:id/faq/entries 批量删除FAQ条目
POST /knowledge-bases/:id/faq/search 混合搜索FAQ
GET /knowledge-bases/:id/faq/entries/export 导出FAQ条目(CSV)
GET /faq/import/progress/:task_id 获取FAQ导入进度
PUT /knowledge-bases/:id/faq/import/last-result/display 更新导入结果显示状态

GET /knowledge-bases/:id/faq/entries - 获取FAQ条目列表

查询参数:

  • page: 页码（默认 1）
  • page_size: 每页条数（默认 20）
  • tag_id: 按标签ID筛选（可选）
  • keyword: 关键字搜索（可选）
  • search_field: 搜索字段（可选），可选值：
    • standard_question: 只搜索标准问题
    • similar_questions: 只搜索相似问法
    • answers: 只搜索答案
    • 留空或不传：搜索全部字段
  • sort_order: 排序方式（可选），asc 表示按更新时间正序，默认按更新时间倒序

请求:

# 搜索全部字段
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10&keyword=密码' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json'

# 只搜索标准问题
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=密码&search_field=standard_question' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ'

# 只搜索相似问法
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=忘记&search_field=similar_questions' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ'

# 只搜索答案
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=点击&search_field=answers' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ'

响应:

{
    "data": {
        "total": 100,
        "page": 1,
        "page_size": 10,
        "data": [
            {
                "id": "faq-00000001",
                "chunk_id": "chunk-00000001",
                "knowledge_id": "knowledge-00000001",
                "knowledge_base_id": "kb-00000001",
                "tag_id": "tag-00000001",
                "is_enabled": true,
                "standard_question": "如何重置密码？",
                "similar_questions": ["忘记密码怎么办", "密码找回"],
                "negative_questions": ["如何修改用户名"],
                "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
                "index_mode": "hybrid",
                "chunk_type": "faq",
                "created_at": "2025-08-12T10:00:00+08:00",
                "updated_at": "2025-08-12T10:00:00+08:00"
            }
        ]
    },
    "success": true
}

POST /knowledge-bases/:id/faq/entries - 批量导入FAQ条目

请求参数:

  • mode: 导入模式，append（追加）或 replace（替换）
  • entries: FAQ条目数组
  • knowledge_id: 关联的知识ID（可选）

请求:

curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "append",
    "entries": [
        {
            "standard_question": "如何联系客服？",
            "similar_questions": ["客服电话", "在线客服"],
            "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
            "tag_id": "tag-00000001"
        },
        {
            "standard_question": "退款政策是什么？",
            "answers": ["我们提供7天无理由退款服务。"]
        }
    ]
}'

响应:

{
    "data": {
        "task_id": "task-00000001"
    },
    "success": true
}

注：批量导入为异步操作，返回任务ID用于追踪进度。

POST /knowledge-bases/:id/faq/entry - 创建单个FAQ条目

同步创建单个FAQ条目，适用于单条录入场景。会自动检查标准问和相似问是否与已有FAQ重复。

请求参数:

  • standard_question: 标准问（必填）
  • similar_questions: 相似问数组（可选）
  • negative_questions: 反例问题数组（可选）
  • answers: 答案数组（必填）
  • tag_id: 标签ID（可选）
  • is_enabled: 是否启用（可选，默认true）

请求:

curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entry' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "standard_question": "如何联系客服？",
    "similar_questions": ["客服电话", "在线客服"],
    "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
    "tag_id": "tag-00000001",
    "is_enabled": true
}'

响应:

{
    "data": {
        "id": "faq-00000001",
        "chunk_id": "chunk-00000001",
        "knowledge_id": "knowledge-00000001",
        "knowledge_base_id": "kb-00000001",
        "tag_id": "tag-00000001",
        "is_enabled": true,
        "standard_question": "如何联系客服？",
        "similar_questions": ["客服电话", "在线客服"],
        "negative_questions": [],
        "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
        "index_mode": "hybrid",
        "chunk_type": "faq",
        "created_at": "2025-08-12T10:00:00+08:00",
        "updated_at": "2025-08-12T10:00:00+08:00"
    },
    "success": true
}

错误响应（标准问或相似问重复时）:

{
    "success": false,
    "error": {
        "code": "BAD_REQUEST",
        "message": "标准问与已有FAQ重复"
    }
}

PUT /knowledge-bases/:id/faq/entries/:entry_id - 更新单个FAQ条目

请求:

curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/faq-00000001' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "standard_question": "如何重置账户密码？",
    "similar_questions": ["忘记密码怎么办", "密码找回", "重置密码"],
    "answers": ["您可以通过以下步骤重置密码：1. 点击登录页面的\"忘记密码\" 2. 输入注册邮箱 3. 查收重置邮件"],
    "is_enabled": true
}'

响应:

{
    "success": true
}

GET /knowledge-bases/:id/faq/entries/:entry_id - 获取单个FAQ条目

根据 seq_id 获取单个 FAQ 条目的详细信息。

请求:

curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/1' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json'

响应:

{
    "data": {
        "id": "faq-00000001",
        "seq_id": 1,
        "chunk_id": "chunk-00000001",
        "knowledge_id": "knowledge-00000001",
        "knowledge_base_id": "kb-00000001",
        "tag_id": "tag-00000001",
        "is_enabled": true,
        "standard_question": "如何重置密码？",
        "similar_questions": ["忘记密码怎么办", "密码找回"],
        "negative_questions": [],
        "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
        "index_mode": "hybrid",
        "chunk_type": "faq",
        "created_at": "2025-08-12T10:00:00+08:00",
        "updated_at": "2025-08-12T10:00:00+08:00"
    },
    "success": true
}

POST /knowledge-bases/:id/faq/entries/:entry_id/similar-questions - 添加相似问题

为指定的 FAQ 条目追加相似问法。

请求参数:

  • similar_questions: 要追加的相似问题数组（必填）

请求:

curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/1/similar-questions' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "similar_questions": ["怎样修改密码", "密码重置方法"]
}'

响应:

{
    "data": {
        "id": "faq-00000001",
        "seq_id": 1,
        "standard_question": "如何重置密码？",
        "similar_questions": ["忘记密码怎么办", "密码找回", "怎样修改密码", "密码重置方法"],
        "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
        "is_enabled": true,
        "chunk_type": "faq",
        "created_at": "2025-08-12T10:00:00+08:00",
        "updated_at": "2025-08-12T11:00:00+08:00"
    },
    "success": true
}

PUT /knowledge-bases/:id/faq/entries/fields - 批量更新FAQ字段

支持按条目ID或按标签ID批量更新 FAQ 条目的多个字段（启用状态、推荐状态、标签等）。

请求参数:

  • by_id: 按条目 seq_id 更新（可选），键为 seq_id，值为要更新的字段
  • by_tag: 按标签 seq_id 更新（可选），键为 tag_seq_id，值为要更新的字段
  • exclude_ids: 排除的条目 seq_id 列表（与 by_tag 配合使用，可选）

每个更新对象支持的字段：

  • is_enabled: 是否启用（可选）
  • is_recommended: 是否推荐（可选）
  • tag_id: 标签ID（可选）

请求:

curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/fields' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "by_id": {
        "1": {"is_enabled": true, "is_recommended": false},
        "2": {"is_enabled": false}
    },
    "by_tag": {
        "100": {"is_enabled": true}
    },
    "exclude_ids": [3, 4]
}'

响应:

{
    "success": true
}

PUT /knowledge-bases/:id/faq/entries/tags - 批量更新FAQ标签

请求:

curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/tags' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "updates": {
        "faq-00000001": "tag-00000001",
        "faq-00000002": "tag-00000002",
        "faq-00000003": null
    }
}'

注：设置为 null 可清除标签关联。

响应:

{
    "success": true
}

DELETE /knowledge-bases/:id/faq/entries - 批量删除FAQ条目

请求:

curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "ids": ["faq-00000001", "faq-00000002"]
}'

响应:

{
    "success": true
}

POST /knowledge-bases/:id/faq/search - 混合搜索FAQ

请求参数:

  • query_text: 搜索查询文本
  • vector_threshold: 向量相似度阈值（0-1）
  • match_count: 返回结果数量（最大200）

请求:

curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/search' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "query_text": "如何重置密码",
    "vector_threshold": 0.5,
    "match_count": 10
}'

响应:

{
    "data": [
        {
            "id": "faq-00000001",
            "chunk_id": "chunk-00000001",
            "knowledge_id": "knowledge-00000001",
            "knowledge_base_id": "kb-00000001",
            "tag_id": "tag-00000001",
            "is_enabled": true,
            "standard_question": "如何重置密码？",
            "similar_questions": ["忘记密码怎么办", "密码找回"],
            "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
            "chunk_type": "faq",
            "score": 0.95,
            "match_type": "vector",
            "created_at": "2025-08-12T10:00:00+08:00",
            "updated_at": "2025-08-12T10:00:00+08:00"
        }
    ],
    "success": true
}

GET /knowledge-bases/:id/faq/entries/export - 导出FAQ条目

将知识库下的所有 FAQ 条目导出为 CSV 文件。

请求:

curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/export' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--output faq_export.csv

响应:

CSV 文件下载（Content-Type: text/csv）

GET /faq/import/progress/:task_id - 获取FAQ导入进度

查询异步 FAQ 导入任务的执行进度。任务 ID 由批量导入接口返回。

请求:

curl --location 'http://localhost:8080/api/v1/faq/import/progress/task-00000001' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json'

响应:

{
    "data": {
        "task_id": "task-00000001",
        "status": "completed",
        "total": 100,
        "success_count": 98,
        "failed_count": 2,
        "failed_entries": [
            {
                "index": 5,
                "standard_question": "重复的问题",
                "error": "标准问与已有FAQ重复"
            }
        ],
        "success_entries": []
    },
    "success": true
}

注：status 可能的值为 pending、processing、completed、failed。

PUT /knowledge-bases/:id/faq/import/last-result/display - 更新导入结果显示状态

更新上一次 FAQ 导入结果的显示状态，用于控制前端是否展示导入结果提示。

请求参数:

  • display_status: 显示状态（如 "dismissed"）

请求:

curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/import/last-result/display' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
    "display_status": "dismissed"
}'

响应:

{
    "success": true
}
Reference in New Issue View Git Blame Copy Permalink