244 lines
11 KiB
Markdown
244 lines
11 KiB
Markdown
# 素材专家检索 —— 内网接口对接说明
|
||
|
||
本文档说明 AI 智能写作中「素材收集专家」的检索机制、内网知识库接口的对接逻辑、
|
||
涉及的代码文件,以及常见错误的排查方式。
|
||
|
||
---
|
||
|
||
## 1. 检索来源切换
|
||
|
||
素材专家支持多种检索来源,通过**后端配置文件**统一切换,**无需改动任何代码**。
|
||
|
||
配置位置:`offline-backend-20260512/backend/config.yaml`
|
||
|
||
```yaml
|
||
ai_writing:
|
||
# 检索来源开关:internet=互联网检索(默认)/ intranet=内网知识库 / tavily / demo
|
||
search_provider: internet
|
||
# 以下两项仅在 search_provider=intranet 时生效
|
||
intranet_search_url: http://10.106.57.180:7863/knowledge_base/search_docs_es
|
||
intranet_knowledge_base: samples
|
||
```
|
||
|
||
| `search_provider` 取值 | 含义 |
|
||
|---|---|
|
||
| `internet` | 互联网检索(DuckDuckGo),失败时回退到 demo 演示素材。**当前默认值** |
|
||
| `intranet` | 内网知识库检索(调用 `search_docs_es` 接口) |
|
||
| `tavily` | Tavily 互联网检索 |
|
||
| `demo` | 内置演示素材,仅用于本地调试 |
|
||
|
||
> 内网接口联通后,把 `search_provider` 改为 `intranet` 即可切换。
|
||
> 配置文件支持热加载(`get_app_config()` 按 mtime 自动重载),改完一般无需重启后端。
|
||
|
||
---
|
||
|
||
## 1.5 检索关键词数量
|
||
|
||
素材专家的检索词数量由**用户在写作表单中指定**(「检索关键词数量」输入框,
|
||
范围 `1~10`,默认 `6`)。数量越多素材越全面,但检索与排序更耗时。
|
||
|
||
- 该参数随 `POST /api/ai-writing/start` 的 `keyword_count` 字段传入,写入 `AIWritingState.keyword_count`。
|
||
- `researcher_node` 用它决定让 LLM 生成多少个检索词、并发检索多少个方向
|
||
(`EXTRACT_KEYWORDS_USER` prompt 按该数量格式化,`search_keywords = keywords[:keyword_count]`)。
|
||
- 非法值(缺省 / 越界 / 非数字)由前后端双重兜底:后端 `_resolve_keyword_count()`
|
||
规整到 `[1, 10]`,越界回退默认 `6`。
|
||
- 补充搜索(`re_search`)时用户额外添加的关键词不会被该上限截断。
|
||
|
||
---
|
||
|
||
## 1.6 素材总量上限
|
||
|
||
素材收集专家最终保留的素材**总条数**由后端配置文件统一控制,并按检索词数**均分**到每个词。
|
||
|
||
配置位置:`offline-backend-20260512/backend/config.yaml` 的 `ai_writing` 段:
|
||
|
||
```yaml
|
||
ai_writing:
|
||
# 素材总量上限,范围 1~100,非法值回退 20
|
||
max_materials: 20
|
||
```
|
||
|
||
均分规则 —— `每个检索词的检索条数 = ⌈ max_materials / 实际检索词数 ⌉`(向上取整):
|
||
|
||
| `max_materials` | 检索词数 | 每词检索条数 |
|
||
|---|---|---|
|
||
| 20 | 1 | 20 |
|
||
| 20 | 2 | 10 |
|
||
| 20 | 3 | 7(共 21,合并后截断到 20) |
|
||
| 20 | 5 | 4 |
|
||
|
||
- 各检索词按上表条数检索 → 合并去重 → 最终统一截断到 `max_materials`。
|
||
- 向上取整是为了保证去重后素材数仍能接近上限;去重后实际条数可能略少于上限(不同词命中同一篇),属正常。
|
||
- 与 [1.5](#15-检索关键词数量) 的关系:`keyword_count` 决定**搜几个词**,`max_materials` 决定**总共要多少条**,两者相除得到每词条数。
|
||
- 涉及代码:`researcher.py` 的 `_resolve_max_materials()`(读配置 + 规整)与 `_per_keyword_limit()`(均分计算)。
|
||
|
||
> `config.yaml` 支持热加载,改完一般无需重启后端。
|
||
|
||
---
|
||
|
||
## 2. 内网接口规格
|
||
|
||
- **地址**:`http://10.106.57.180:7863/knowledge_base/search_docs_es`
|
||
- **方法**:`POST`
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"query": "检索关键词",
|
||
"knowledge_base_name": "samples",
|
||
"ts": "yes"
|
||
}
|
||
```
|
||
|
||
- **响应体**:一个数组,每个元素结构如下:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"page_content": "正文片段",
|
||
"metadata": {
|
||
"m_title": "标题",
|
||
"content": "内容",
|
||
"recUuid": "原文id",
|
||
"m_publish":"发布时间",
|
||
"source1": "来源"
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
我们需要的字段都在 `metadata` 里。
|
||
|
||
### 字段映射
|
||
|
||
后端把内网响应映射为统一的 `SearchResult` 结构:
|
||
|
||
| 内网响应字段 | SearchResult 字段 | 说明 |
|
||
|--------------------------|--------------------|------|
|
||
| `metadata.m_title` | `title` | 标题,缺省为「(无标题)」 |
|
||
| `metadata.content` | `content` | 内容,截断到 500 字 |
|
||
| `metadata.source1` | `source` | 来源,缺省为「内网知识库」 |
|
||
| `metadata.m_publish` | `published_at` | 发布时间 |
|
||
| `metadata.recUuid` | `recUuid` | 原文 id,用于前端拼接「查看原文」链接 |
|
||
| — | `url` | 固定为空,原文地址由前端依据 `recUuid` 拼接 |
|
||
| — | `relevance_score` | 接口不返回分值,按返回顺序赋递减分以保留 ES 排序 |
|
||
| — | `source_type` | 固定为 `"intranet"` |
|
||
|
||
---
|
||
|
||
## 3. 对接逻辑与涉及文件
|
||
|
||
### 后端
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `packages/harness/deerflow/agents/ai_writing/search/intranet_stub.py` | **内网检索适配器** `IntranetSearchProvider`。发起 POST 请求、解析响应、映射为 `SearchResult` |
|
||
| `packages/harness/deerflow/agents/ai_writing/search/__init__.py` | `get_search_provider()` 工厂函数,依据 `search_provider` 配置返回对应 provider |
|
||
| `packages/harness/deerflow/agents/ai_writing/search/base.py` | `SearchResult` 数据结构 + `BaseSearchProvider` 抽象基类 |
|
||
| `packages/harness/deerflow/agents/ai_writing/nodes/researcher.py` | 素材收集专家节点,调用 provider 检索并把结果合并、排序为素材包 |
|
||
| `app/gateway/routers/ai_writing.py` | `_ai_writing_config()` 读取 `config.yaml` 的 `ai_writing` 段,经 `_make_config()` 注入运行时 |
|
||
| `config.yaml` | `ai_writing` 段,检索来源开关与内网接口地址 |
|
||
|
||
调用链:
|
||
|
||
```
|
||
ai_writing.py(_make_config 注入 ai_writing_config)
|
||
→ researcher_node
|
||
→ get_search_provider(ai_writing_config) # 依据 search_provider 选择
|
||
→ IntranetSearchProvider.search() # POST search_docs_es
|
||
→ SearchResult[] # 字段映射
|
||
```
|
||
|
||
### 前端
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `src/core/config/index.ts` | `INTRANET_SOURCE_URL_BASE` 原文详情页地址前缀 + `buildIntranetSourceUrl()` 构造函数 |
|
||
| `src/open-canvas/components/ai-writing/MaterialItem.tsx` | 素材卡片,`recUuid` 非空时显示「查看原文」按钮 |
|
||
| `src/open-canvas/components/ai-writing/CompletedInterventionCard.tsx` | 历史回显的素材卡,「原文」链接同样基于 `recUuid` |
|
||
| `src/open-canvas/api/ai-writing.ts` | `normalizeMaterial()` 把后端 snake_case 字段转为前端 camelCase(含 `recUuid`) |
|
||
|
||
「查看原文」链接拼接规则:
|
||
|
||
```
|
||
INTRANET_SOURCE_URL_BASE + recUuid
|
||
= https://chlib.b.uat.4.cn/knowlibrary/#/knowledge/mid_detail?recUuid={recUuid}
|
||
```
|
||
|
||
- 仅当素材的 `recUuid` **非空**时才显示「查看原文」按钮。
|
||
- 点击直接 `window.open(...)` 新标签页打开,不做站内跳转。
|
||
|
||
---
|
||
|
||
## 4. 错误处理与排查
|
||
|
||
### 4.1 内网检索返回空 / 调不通
|
||
|
||
**现象**:切到 `intranet` 后,素材专家时间线出现琥珀色告警「ES 波动导致检索异常」,
|
||
下方显示真实报错原因;若完全无结果,再提示「未检索到任何素材」。
|
||
|
||
`IntranetSearchProvider.search()` 对所有异常(连接失败、超时、非 2xx、JSON 解析失败)
|
||
都做了兜底:**捕获后记录 warning 日志、把原因收集到 `provider.errors`,并返回空列表**,
|
||
不会让整个写作流程崩溃。`researcher_node` 在检索结束后取出 `provider.errors`,
|
||
以非致命的 `notice` 事件推送到前端时间线(标题「ES 波动导致检索异常」+ 真实原因),
|
||
**接口报错不影响写作流程继续**。
|
||
|
||
> 容错相关代码:
|
||
> - 检索异常收集:`intranet_stub.py` / `duckduckgo_search.py` 的 `errors` 列表
|
||
> - 告警事件发出:`researcher.py` 的 `_notice()` 与 `progress_events`
|
||
> - 模型调用异常:`researcher.py`(检索词/排序)、`writer_outline.py` / `writer_draft.py` /
|
||
> `editor.py` 均会发出「模型错误」事件(致命错误用 `error`,可兜底的用 `notice`)
|
||
> - 前端展示:`TimelineStep.tsx` 渲染 `notice`(琥珀)/ `error`(红色)的标题 + 真实原因
|
||
|
||
排查步骤:
|
||
|
||
1. **确认网络可达**:在后端所在机器执行
|
||
`curl -X POST http://10.106.57.180:7863/knowledge_base/search_docs_es -H "Content-Type: application/json" -d "{\"query\":\"测试\",\"knowledge_base_name\":\"samples\",\"ts\":\"yes\"}"`
|
||
2. **查看后端日志**:搜索关键字 `intranet search failed`,会打印具体异常(连接超时 / DNS / 401 等)。
|
||
3. **确认配置**:`config.yaml` 的 `intranet_search_url`、`intranet_knowledge_base` 是否正确。
|
||
|
||
空结果时前端已有兜底:素材确认卡会弹出「未检索到任何素材,是否在无素材的情况下继续写作」,
|
||
用户可以选择「重新搜索」或「无数据继续写作」。
|
||
|
||
### 4.2 字段缺失 / 响应结构变化
|
||
|
||
`search()` 对每个字段都用 `or` 兜底(如 `m_title` 缺失时回退为「(无标题)」),
|
||
单条数据字段缺失不会导致整批失败。
|
||
|
||
若内网接口改为「数组外包一层 `data`/`results`」的结构,适配器已兼容;
|
||
若改成其它结构,需修改 `intranet_stub.py` 中解析 `items` 的逻辑。
|
||
|
||
### 4.3 「查看原文」按钮不显示
|
||
|
||
**原因**:该素材的 `recUuid` 为空。这是预期行为 —— 只有内网知识库素材才带 `recUuid`,
|
||
互联网检索(`internet`/`tavily`/`demo`)的素材没有 `recUuid`,不显示「查看原文」。
|
||
|
||
如需让互联网素材也能跳转,需另行调整 `MaterialItem.tsx` 的显示条件。
|
||
|
||
### 4.4 原文链接打不开 / 地址不对
|
||
|
||
「查看原文」地址前缀写在 `src/core/config/index.ts` 的 `INTRANET_SOURCE_URL_BASE`。
|
||
若内网原文详情页地址有变,只改这一个常量即可。
|
||
|
||
### 4.5 检索到的素材全是无关内容
|
||
|
||
**现象**:素材卡片内容与写作意图完全不沾边。
|
||
|
||
**排查**:检查后端日志里素材专家实际用的检索词。常见原因是模型把关键词提取
|
||
提示词模板里的占位符(如「关键词1」「...」)当成真关键词去检索了。
|
||
|
||
`researcher.py` 的 `_clean_keywords()` 已对此做防御:剔除 `关键词\d*` / `keyword\d*` /
|
||
`...` 等占位符,全部被滤掉时回退为写作意图本身。若仍出现,检查
|
||
`researcher_prompts.py` 的 `EXTRACT_KEYWORDS` 提示词是否又引入了易被误抄的示例占位符。
|
||
|
||
---
|
||
|
||
## 5. 联调上线步骤
|
||
|
||
1. 确认后端机器能访问 `10.106.57.180:7863`。
|
||
2. 把 `config.yaml` 的 `ai_writing.search_provider` 改为 `intranet`。
|
||
3. 后端配置热加载生效(或重启后端)。
|
||
4. 进入 AI 智能写作页面,发起一次写作,观察素材收集专家是否返回内网素材。
|
||
5. 校验素材卡片的标题/来源/时间显示正确,「查看原文」能跳到内网详情页。
|
||
6. 如检索为空,按 [4.1](#41-内网检索返回空--调不通) 排查。
|