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:
+291
-231
@@ -2,55 +2,54 @@
|
||||
|
||||
[返回目录](./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` | 更新导入结果显示状态 |
|
||||
FAQ 接口分为两组:
|
||||
|
||||
## GET `/knowledge-bases/:id/faq/entries` - 获取FAQ条目列表
|
||||
- `/knowledge-bases/:id/faq/*`:知识库范围内的 FAQ 条目 CRUD、批量操作、搜索与导入导出。
|
||||
- `/faq/import/progress/:task_id`:**不属于知识库分组**,用于查询异步导入/dry-run 任务的进度,仅需任务 ID 即可调用。
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
| ------ | ----------------------------------------------------------------- | --------------------------------- |
|
||||
| GET | `/knowledge-bases/:id/faq/entries` | 获取 FAQ 条目列表 |
|
||||
| GET | `/knowledge-bases/:id/faq/entries/export` | 导出 FAQ 条目(CSV) |
|
||||
| GET | `/knowledge-bases/:id/faq/entries/:entry_id` | 获取单个 FAQ 条目(按 seq_id) |
|
||||
| POST | `/knowledge-bases/:id/faq/entries` | 批量 Upsert FAQ 条目(异步) |
|
||||
| POST | `/knowledge-bases/:id/faq/entry` | 同步创建单个 FAQ 条目 |
|
||||
| PUT | `/knowledge-bases/:id/faq/entries/:entry_id` | 更新单个 FAQ 条目 |
|
||||
| POST | `/knowledge-bases/:id/faq/entries/:entry_id/similar-questions` | 为 FAQ 条目追加相似问 |
|
||||
| PUT | `/knowledge-bases/:id/faq/entries/fields` | 批量更新字段(启用/推荐/标签) |
|
||||
| PUT | `/knowledge-bases/:id/faq/entries/tags` | 批量更新标签 |
|
||||
| DELETE | `/knowledge-bases/:id/faq/entries` | 批量删除 FAQ 条目 |
|
||||
| POST | `/knowledge-bases/:id/faq/search` | FAQ 混合搜索 |
|
||||
| PUT | `/knowledge-bases/:id/faq/import/last-result/display` | 更新上次导入结果卡片显示状态 |
|
||||
| GET | `/faq/import/progress/:task_id` | 查询 FAQ 导入任务进度(公共) |
|
||||
|
||||
> **路径参数说明**:`:entry_id` 始终是 FAQ 条目的 `seq_id`(整数),不是字符串形式的 ID。同理,批量接口中的 `by_id` / `by_tag` / `exclude_ids` / `ids` 字段均为 `seq_id` 列表(整数)。
|
||||
|
||||
## 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` 表示按更新时间正序,默认按更新时间倒序
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------------ | ------ | ---- | --------------------------------------------------------------------------------------------- |
|
||||
| page | int | 否 | 页码,默认 1 |
|
||||
| page_size | int | 否 | 每页数量,默认 20 |
|
||||
| tag_id | int | 否 | 按标签 `seq_id` 过滤 |
|
||||
| keyword | string | 否 | 关键字搜索 |
|
||||
| search_field | string | 否 | 搜索字段:`standard_question` / `similar_questions` / `answers`,留空则全字段搜索 |
|
||||
| sort_order | string | 否 | 排序方式,`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'
|
||||
--header 'X-API-Key: sk-xxxxx'
|
||||
|
||||
# 只搜索标准问题
|
||||
# 仅搜索标准问
|
||||
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'
|
||||
--header 'X-API-Key: sk-xxxxx'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
@@ -63,16 +62,19 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/en
|
||||
"page_size": 10,
|
||||
"data": [
|
||||
{
|
||||
"id": "faq-00000001",
|
||||
"id": 1,
|
||||
"chunk_id": "chunk-00000001",
|
||||
"knowledge_id": "knowledge-00000001",
|
||||
"knowledge_base_id": "kb-00000001",
|
||||
"tag_id": "tag-00000001",
|
||||
"tag_id": 12,
|
||||
"tag_name": "账户",
|
||||
"is_enabled": true,
|
||||
"is_recommended": false,
|
||||
"standard_question": "如何重置密码?",
|
||||
"similar_questions": ["忘记密码怎么办", "密码找回"],
|
||||
"negative_questions": ["如何修改用户名"],
|
||||
"answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
|
||||
"answer_strategy": "all",
|
||||
"index_mode": "hybrid",
|
||||
"chunk_type": "faq",
|
||||
"created_at": "2025-08-12T10:00:00+08:00",
|
||||
@@ -84,18 +86,94 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/en
|
||||
}
|
||||
```
|
||||
|
||||
## POST `/knowledge-bases/:id/faq/entries` - 批量导入FAQ条目
|
||||
## GET `/knowledge-bases/:id/faq/entries/export` - 导出 FAQ 条目
|
||||
|
||||
**请求参数**:
|
||||
- `mode`: 导入模式,`append`(追加)或 `replace`(替换)
|
||||
- `entries`: FAQ条目数组
|
||||
- `knowledge_id`: 关联的知识ID(可选)
|
||||
将知识库下的所有 FAQ 条目导出为 CSV(UTF-8 带 BOM,Excel 兼容)。
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/export' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--output faq_export.csv
|
||||
```
|
||||
|
||||
**响应**: `Content-Type: text/csv; charset=utf-8`,附带文件名 `faq_export.csv`。
|
||||
|
||||
## 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-xxxxx'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": 1,
|
||||
"chunk_id": "chunk-00000001",
|
||||
"knowledge_id": "knowledge-00000001",
|
||||
"knowledge_base_id": "kb-00000001",
|
||||
"tag_id": 12,
|
||||
"tag_name": "账户",
|
||||
"is_enabled": true,
|
||||
"is_recommended": false,
|
||||
"standard_question": "如何重置密码?",
|
||||
"similar_questions": ["忘记密码怎么办", "密码找回"],
|
||||
"negative_questions": [],
|
||||
"answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
|
||||
"answer_strategy": "all",
|
||||
"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` - 批量 Upsert FAQ 条目(异步)
|
||||
|
||||
**异步**批量导入或更新 FAQ 条目。接口立即返回 `task_id`,调用方需通过 `GET /faq/import/progress/:task_id` 查询进度与结果。
|
||||
|
||||
支持 `dry_run=true`:异步执行仅校验(格式 / 批内重复 / 与库内重复 / 内容安全),不实际写入。
|
||||
|
||||
**请求体(`types.FAQBatchUpsertPayload`)**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ------------ | -------------------------- | ---- | ----------------------------------------------------------------------------------- |
|
||||
| entries | `[]FAQEntryPayload` | 是 | FAQ 条目数组 |
|
||||
| mode | string | 是 | `append` 或 `replace`(替换会清空已有条目) |
|
||||
| knowledge_id | string | 否 | 关联的 FAQ Knowledge ID(不传则使用知识库默认 FAQ knowledge) |
|
||||
| task_id | string | 否 | 任务 ID,不传则自动生成 UUID |
|
||||
| dry_run | boolean | 否 | 仅验证不导入 |
|
||||
|
||||
`FAQEntryPayload` 字段:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ------------------- | --------- | ---- | ------------------------------------------------------------- |
|
||||
| id | int64 | 否 | 指定 `seq_id`(数据迁移场景,需小于自增起始值 100000000) |
|
||||
| standard_question | string | 是 | 标准问 |
|
||||
| similar_questions | string[] | 否 | 相似问列表 |
|
||||
| negative_questions | string[] | 否 | 反例问题列表 |
|
||||
| answers | string[] | 否 | 答案列表 |
|
||||
| answer_strategy | string | 否 | 答案返回策略:`all` 或 `random` |
|
||||
| tag_id | int64 | 否 | 标签 `seq_id` |
|
||||
| tag_name | string | 否 | 标签名(用于按名匹配标签) |
|
||||
| is_enabled | boolean | 否 | 是否启用 |
|
||||
| is_recommended | boolean | 否 | 是否推荐 |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"mode": "append",
|
||||
@@ -104,7 +182,7 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/en
|
||||
"standard_question": "如何联系客服?",
|
||||
"similar_questions": ["客服电话", "在线客服"],
|
||||
"answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
|
||||
"tag_id": "tag-00000001"
|
||||
"tag_id": 1
|
||||
},
|
||||
{
|
||||
"standard_question": "退款政策是什么?",
|
||||
@@ -118,38 +196,30 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/en
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"task_id": "task-00000001"
|
||||
},
|
||||
"data": { "task_id": "task-00000001" },
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
注:批量导入为异步操作,返回任务ID用于追踪进度。
|
||||
> 用 `GET /faq/import/progress/:task_id` 查询任务最终状态。
|
||||
|
||||
## POST `/knowledge-bases/:id/faq/entry` - 创建单个FAQ条目
|
||||
## POST `/knowledge-bases/:id/faq/entry` - 同步创建单个 FAQ 条目
|
||||
|
||||
同步创建单个FAQ条目,适用于单条录入场景。会自动检查标准问和相似问是否与已有FAQ重复。
|
||||
**同步**创建单条 FAQ 条目,会即时校验标准问/相似问与库内已有条目的重复。
|
||||
|
||||
**请求参数**:
|
||||
- `standard_question`: 标准问(必填)
|
||||
- `similar_questions`: 相似问数组(可选)
|
||||
- `negative_questions`: 反例问题数组(可选)
|
||||
- `answers`: 答案数组(必填)
|
||||
- `tag_id`: 标签ID(可选)
|
||||
- `is_enabled`: 是否启用(可选,默认true)
|
||||
**请求体**: 同上 `FAQEntryPayload`(`standard_question` 必填)。
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entry' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"standard_question": "如何联系客服?",
|
||||
"similar_questions": ["客服电话", "在线客服"],
|
||||
"answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
|
||||
"tag_id": "tag-00000001",
|
||||
"tag_id": 1,
|
||||
"is_enabled": true
|
||||
}'
|
||||
```
|
||||
@@ -159,16 +229,19 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/en
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": "faq-00000001",
|
||||
"id": 1,
|
||||
"chunk_id": "chunk-00000001",
|
||||
"knowledge_id": "knowledge-00000001",
|
||||
"knowledge_base_id": "kb-00000001",
|
||||
"tag_id": "tag-00000001",
|
||||
"tag_id": 1,
|
||||
"tag_name": "客服",
|
||||
"is_enabled": true,
|
||||
"is_recommended": false,
|
||||
"standard_question": "如何联系客服?",
|
||||
"similar_questions": ["客服电话", "在线客服"],
|
||||
"negative_questions": [],
|
||||
"answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
|
||||
"answer_strategy": "all",
|
||||
"index_mode": "hybrid",
|
||||
"chunk_type": "faq",
|
||||
"created_at": "2025-08-12T10:00:00+08:00",
|
||||
@@ -190,13 +263,15 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/en
|
||||
}
|
||||
```
|
||||
|
||||
## PUT `/knowledge-bases/:id/faq/entries/:entry_id` - 更新单个FAQ条目
|
||||
## PUT `/knowledge-bases/:id/faq/entries/:entry_id` - 更新单个 FAQ 条目
|
||||
|
||||
按 `seq_id` 更新单条 FAQ 条目,请求体同 `FAQEntryPayload`。
|
||||
|
||||
**请求**:
|
||||
|
||||
```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' \
|
||||
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/1' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"standard_question": "如何重置账户密码?",
|
||||
@@ -206,107 +281,61 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-0
|
||||
}'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
**响应**: 返回更新后的 FAQ 条目,结构同创建接口。
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
## POST `/knowledge-bases/:id/faq/entries/:entry_id/similar-questions` - 追加相似问
|
||||
|
||||
## GET `/knowledge-bases/:id/faq/entries/:entry_id` - 获取单个FAQ条目
|
||||
向指定 FAQ 条目(`seq_id`)追加相似问。
|
||||
|
||||
根据 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`: 要追加的相似问题数组(必填)
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | -------- | ---- | --------------------- |
|
||||
| similar_questions | string[] | 是 | 要追加的相似问数组 |
|
||||
|
||||
**请求**:
|
||||
|
||||
```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 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"similar_questions": ["怎样修改密码", "密码重置方法"]
|
||||
}'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
**响应**: 返回追加后的完整 FAQ 条目。
|
||||
|
||||
```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` - 批量更新字段
|
||||
|
||||
## PUT `/knowledge-bases/:id/faq/entries/fields` - 批量更新FAQ字段
|
||||
**统一**的批量字段更新接口,支持同时更新 `is_enabled` / `is_recommended` / `tag_id`,并支持两种作用域:
|
||||
|
||||
支持按条目ID或按标签ID批量更新 FAQ 条目的多个字段(启用状态、推荐状态、标签等)。
|
||||
- **按条目 ID** (`by_id`):键为条目 `seq_id`,值为该条目要更新的字段。
|
||||
- **按标签 ID** (`by_tag`):键为标签 `seq_id`,对该标签下的所有条目应用相同的字段更新;可配合 `exclude_ids` 排除部分条目。
|
||||
|
||||
**请求参数**:
|
||||
- `by_id`: 按条目 seq_id 更新(可选),键为 seq_id,值为要更新的字段
|
||||
- `by_tag`: 按标签 seq_id 更新(可选),键为 tag_seq_id,值为要更新的字段
|
||||
- `exclude_ids`: 排除的条目 seq_id 列表(与 by_tag 配合使用,可选)
|
||||
`by_id` 和 `by_tag` 至少传一项;二者可同时使用。
|
||||
|
||||
每个更新对象支持的字段:
|
||||
- `is_enabled`: 是否启用(可选)
|
||||
- `is_recommended`: 是否推荐(可选)
|
||||
- `tag_id`: 标签ID(可选)
|
||||
**请求体(`types.FAQEntryFieldsBatchUpdate`)**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ----------- | --------------------------------- | ---- | ------------------------------------------ |
|
||||
| by_id | `map[int64]FAQEntryFieldsUpdate` | 否 | 按条目 `seq_id` 更新 |
|
||||
| by_tag | `map[int64]FAQEntryFieldsUpdate` | 否 | 按标签 `seq_id` 对该标签下所有条目更新 |
|
||||
| exclude_ids | `int64[]` | 否 | 与 `by_tag` 配合使用,排除指定条目 `seq_id` |
|
||||
|
||||
`FAQEntryFieldsUpdate` 字段(全部可选,仅传入的字段会被更新):
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| -------------- | ------- | -------------- |
|
||||
| is_enabled | boolean | 是否启用 |
|
||||
| is_recommended | boolean | 是否推荐 |
|
||||
| tag_id | int64 | 标签 `seq_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 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"by_id": {
|
||||
@@ -314,7 +343,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-0
|
||||
"2": {"is_enabled": false}
|
||||
},
|
||||
"by_tag": {
|
||||
"100": {"is_enabled": true}
|
||||
"100": {"is_recommended": true}
|
||||
},
|
||||
"exclude_ids": [3, 4]
|
||||
}'
|
||||
@@ -323,76 +352,92 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-0
|
||||
**响应**:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
{ "success": true }
|
||||
```
|
||||
|
||||
## PUT `/knowledge-bases/:id/faq/entries/tags` - 批量更新FAQ标签
|
||||
## PUT `/knowledge-bases/:id/faq/entries/tags` - 批量更新标签
|
||||
|
||||
仅更新标签关联。键为条目 `seq_id`,值为目标标签 `seq_id`;值传 `null` 表示清除标签。
|
||||
|
||||
**请求体**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ------- | --------------------- | ---- | -------------------------------------------- |
|
||||
| updates | `map[int64]int64?` | 是 | 键:条目 `seq_id`;值:标签 `seq_id` 或 `null` |
|
||||
|
||||
**请求**:
|
||||
|
||||
```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 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"updates": {
|
||||
"faq-00000001": "tag-00000001",
|
||||
"faq-00000002": "tag-00000002",
|
||||
"faq-00000003": null
|
||||
"1": 10,
|
||||
"2": 11,
|
||||
"3": null
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
注:设置为 `null` 可清除标签关联。
|
||||
|
||||
**响应**:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
{ "success": true }
|
||||
```
|
||||
|
||||
## DELETE `/knowledge-bases/:id/faq/entries` - 批量删除FAQ条目
|
||||
## DELETE `/knowledge-bases/:id/faq/entries` - 批量删除
|
||||
|
||||
**请求体**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ---- | --------- | ---- | --------------------------------- |
|
||||
| ids | `int64[]` | 是 | 要删除的 FAQ 条目 `seq_id` 列表 |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"ids": ["faq-00000001", "faq-00000002"]
|
||||
"ids": [1, 2, 3]
|
||||
}'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
{ "success": true }
|
||||
```
|
||||
|
||||
## POST `/knowledge-bases/:id/faq/search` - 混合搜索FAQ
|
||||
## POST `/knowledge-bases/:id/faq/search` - FAQ 混合搜索
|
||||
|
||||
**请求参数**:
|
||||
- `query_text`: 搜索查询文本
|
||||
- `vector_threshold`: 向量相似度阈值(0-1)
|
||||
- `match_count`: 返回结果数量(最大200)
|
||||
向量 + 关键字混合检索,支持两级优先级标签召回。
|
||||
|
||||
**请求体(`types.FAQSearchRequest`)**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ----------------------- | --------- | ---- | ----------------------------------------------------------------------------------- |
|
||||
| query_text | string | 是 | 搜索文本 |
|
||||
| vector_threshold | float | 否 | 向量相似度阈值(0–1) |
|
||||
| match_count | int | 否 | 返回数量,默认 10,最大 200 |
|
||||
| first_priority_tag_ids | `int64[]` | 否 | 第一优先级标签 `seq_id` 列表(最高优先召回范围) |
|
||||
| second_priority_tag_ids | `int64[]` | 否 | 第二优先级标签 `seq_id` 列表 |
|
||||
| only_recommended | boolean | 否 | 是否仅返回 `is_recommended=true` 的条目 |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/search' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"query_text": "如何重置密码",
|
||||
"vector_threshold": 0.5,
|
||||
"match_count": 10
|
||||
"match_count": 10,
|
||||
"first_priority_tag_ids": [12],
|
||||
"only_recommended": false
|
||||
}'
|
||||
```
|
||||
|
||||
@@ -402,18 +447,22 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/se
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": "faq-00000001",
|
||||
"id": 1,
|
||||
"chunk_id": "chunk-00000001",
|
||||
"knowledge_id": "knowledge-00000001",
|
||||
"knowledge_base_id": "kb-00000001",
|
||||
"tag_id": "tag-00000001",
|
||||
"tag_id": 12,
|
||||
"tag_name": "账户",
|
||||
"is_enabled": true,
|
||||
"is_recommended": false,
|
||||
"standard_question": "如何重置密码?",
|
||||
"similar_questions": ["忘记密码怎么办", "密码找回"],
|
||||
"answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
|
||||
"answer_strategy": "all",
|
||||
"chunk_type": "faq",
|
||||
"score": 0.95,
|
||||
"match_type": "vector",
|
||||
"matched_question": "忘记密码怎么办",
|
||||
"created_at": "2025-08-12T10:00:00+08:00",
|
||||
"updated_at": "2025-08-12T10:00:00+08:00"
|
||||
}
|
||||
@@ -422,81 +471,92 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/se
|
||||
}
|
||||
```
|
||||
|
||||
## GET `/knowledge-bases/:id/faq/entries/export` - 导出FAQ条目
|
||||
## PUT `/knowledge-bases/:id/faq/import/last-result/display` - 更新上次导入结果显示状态
|
||||
|
||||
将知识库下的所有 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"`)
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| -------------- | ------ | ---- | --------------------- |
|
||||
| display_status | string | 是 | `open` 或 `close` |
|
||||
|
||||
**请求**:
|
||||
|
||||
```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 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"display_status": "dismissed"
|
||||
"display_status": "close"
|
||||
}'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
|
||||
```json
|
||||
{ "success": true }
|
||||
```
|
||||
|
||||
## GET `/faq/import/progress/:task_id` - 查询 FAQ 导入进度
|
||||
|
||||
> **注意**:此接口**不在** `/knowledge-bases/:id/faq` 分组下,路径直接以 `/faq/import/progress/:task_id` 开头。任务 ID 由 `POST /knowledge-bases/:id/faq/entries` 返回。
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
| ------- | ------ | -------------- |
|
||||
| task_id | string | 导入任务的 ID |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location 'http://localhost:8080/api/v1/faq/import/progress/task-00000001' \
|
||||
--header 'X-API-Key: sk-xxxxx'
|
||||
```
|
||||
|
||||
**响应**(节选关键字段):
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"task_id": "task-00000001",
|
||||
"kb_id": "kb-00000001",
|
||||
"knowledge_id": "knowledge-00000001",
|
||||
"status": "completed",
|
||||
"progress": 100,
|
||||
"total": 100,
|
||||
"processed": 100,
|
||||
"success_count": 95,
|
||||
"failed_count": 3,
|
||||
"partial_failed_count": 2,
|
||||
"skipped_count": 0,
|
||||
"failed_entries": [
|
||||
{
|
||||
"index": 5,
|
||||
"reason": "标准问与已有FAQ重复",
|
||||
"standard_question": "重复的问题"
|
||||
}
|
||||
],
|
||||
"success_entries": [
|
||||
{ "index": 0, "seq_id": 101, "standard_question": "如何联系客服?" }
|
||||
],
|
||||
"message": "",
|
||||
"error": "",
|
||||
"created_at": 1736582400,
|
||||
"updated_at": 1736582460,
|
||||
"dry_run": false,
|
||||
"import_mode": "append",
|
||||
"imported_at": "2025-08-12T10:01:00+08:00",
|
||||
"display_status": "open",
|
||||
"processing_time": 60000
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
`status` 可能取值:`pending` / `processing` / `completed` / `failed`。
|
||||
|
||||
当失败条目过多时,`failed_entries` 可能不直接返回,而通过 `failed_entries_url` 提供 CSV 下载地址。
|
||||
|
||||
`dry_run=true` 模式下的任务同样通过此接口查询,`success_entries` 中的 `seq_id` 不会真正写入。
|
||||
|
||||
Reference in New Issue
Block a user