ContextQMD
Back to Weknora

FAQ管理 API

docs/api/faq.md

0.5.114.9 KB
Original Source

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
# 搜索全部字段
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'

响应:

json
{
    "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
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天无理由退款服务。"]
        }
    ]
}'

响应:

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

响应:

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

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

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

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

请求:

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

响应:

json
{
    "success": true
}

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

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

请求:

curl
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'

响应:

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
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": ["怎样修改密码", "密码重置方法"]
}'

响应:

json
{
    "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
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]
}'

响应:

json
{
    "success": true
}

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

请求:

curl
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 可清除标签关联。

响应:

json
{
    "success": true
}

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

请求:

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

响应:

json
{
    "success": true
}

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

请求参数:

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

请求:

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

响应:

json
{
    "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
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
curl --location 'http://localhost:8080/api/v1/faq/import/progress/task-00000001' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json'

响应:

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

响应:

json
{
    "success": true
}