WeKnora/docs/api/faq.md

503 lines
15 KiB
Markdown
Raw Normal View History

# FAQ管理 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------------- | ------------------------ |
| 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
}
```