138 lines
7.7 KiB
Markdown
138 lines
7.7 KiB
Markdown
---
|
|
name: documents
|
|
description: 查内部材料学科知识库(document_search API,7 个学科:胶凝 / 陶瓷 / 玻璃 / 晶体 / 复合 / 耐火 / 检验检测,21W+ 英文学术论文 Markdown 化,跨语言语义检索)。用户找材料领域文献、特定学科论文、材料性能数据时使用;与 research(OpenAlex 外部库)互补,可并用 / 同时试。
|
|
---
|
|
|
|
# Documents
|
|
|
|
部署在 `https://ai.ctc-zc.com:8100/api` 的文档检索 API。后端按 `kb_name` 分库存储 7 个材料学科库(中文命名:胶凝 / 陶瓷基 / 玻璃基 / 晶体材料 / 复合材料 / 耐火材料 / 检验检测,共 21W+ 文件),**文档主体是英文学术论文**(Elsevier 期刊为主,DOI 前缀文件名),每个文档带 `md_content`(整篇 Markdown,LLM 友好)+ 可选的原 PDF 下载。**API 后端有跨语言语义检索**,中英文 query 都能命中英文文档。本 skill 给四个 helper(`list_kb` / `search` / `download` / `health`),用 `run_python` 调用,**不要**自己 `httpx` 裸调。
|
|
|
|
## 何时用
|
|
|
|
- 用户要查材料领域文献(7 个学科:胶凝 / 陶瓷 / 玻璃 / 晶体 / 复合 / 耐火 / 检验检测)
|
|
- 用户要查特定材料性能 / 工艺数据(实验数据 / 表征结果 / 公式 / 表格)
|
|
- 写申报书 / 方案 / 报告需要"国内外现状"段,本库 Markdown 化的论文比 research 拿到的裸 PDF/XML 更直接可用
|
|
- **跟 research 并列**:都是文献检索 —— research 走 OpenAlex 元数据 + Sci-Hub PDF,搜全网;documents 是本地预收的材料学科子集,**已转 Markdown**(LLM 直接读,免 OCR / XML 解析)+ **跨语言语义检索**(中文 query 也能命中英文论文)。找材料类文献优先 documents,找其他学科或要 DOI 走 research,**两者命中不重叠时可并用**
|
|
|
|
## 何时不用
|
|
|
|
- 用户只问通识(直接答)
|
|
- 用户已经给了具体内部文档路径(直接读,不要二次校验)
|
|
|
|
## 准备
|
|
|
|
```python
|
|
from skills.documents.client import list_kb, search, download, health
|
|
```
|
|
|
|
(import 路径由 `run_python` 注入的 `PYTHONPATH` 提供,直接写就行)
|
|
|
|
API key 走 env `DOCUMENT_SEARCH_API_KEY`,未设会抛 `RuntimeError`。base_url 走 env `DOCUMENT_SEARCH_URL`(默认 `https://ai.ctc-zc.com:8100/api`)。
|
|
|
|
## 四个函数
|
|
|
|
### `list_kb() -> list[dict]`
|
|
|
|
列所有有效知识库(分类 1-7)。每条含 `id` / `kb_name` / `ch_name` / `kb_info` / `file_count` 等。
|
|
|
|
```python
|
|
kbs = list_kb()
|
|
for kb in kbs:
|
|
print(kb["id"], kb["kb_name"], kb["ch_name"], kb["file_count"])
|
|
```
|
|
|
|
**用途**:用户没指定库 → 先 `list_kb()` 看有哪些库(中文名 `ch_name` 看分类),再选 `kb_names` / `classification_ids` 缩窄 search 范围。
|
|
|
|
### `search(query, kb_names=None, classification_ids=None, max_documents=6) -> list[dict]`
|
|
|
|
搜文档,返回精简列表,每条带 **`md_content`**(整篇 Markdown 文本)。
|
|
|
|
- `query`:搜索词。**中英文均可** —— 文档主体是英文学术论文,但 API 后端有跨语言语义检索;复杂技术术语用**英文**更精准(`cement hydration` > `水泥水化`),日常概念中文 OK
|
|
- `kb_names`:知识库白名单(从 `list_kb()` 选);`None` 走 server 默认(单库 `mu_34_1740625285897` 胶凝)。**多库联查就显式传**,如 `kb_names=["mu_34_1740625285897", "mu_34_1740625303475"]`
|
|
- `classification_ids`:分类 ID 白名单(1-7,对应 7 个学科库);`None` 不过滤
|
|
- `max_documents`:1-20,默认 6
|
|
|
|
**学科库 → kb_name 速查**(`list_kb()` 拿全量,这里只列常用):
|
|
|
|
| 学科 | kb_name |
|
|
|---|---|
|
|
| 胶凝材料(水泥 / 混凝土 / 砂浆) | `mu_34_1740625285897` |
|
|
| 陶瓷基材料 | `mu_34_1740625303475` |
|
|
| 玻璃基材料 | `mu_34_1740625318986` |
|
|
| 晶体材料 | `mu_34_1740625346474` |
|
|
| 复合材料 | `mu_34_1740625355308` |
|
|
| 耐火材料 | `mu_34_1740625365079` |
|
|
| 检验检测 | `mu_34_1740625376621` |
|
|
|
|
```python
|
|
# 全库搜(走 server 默认单库:胶凝)
|
|
docs = search(query="cement hydration", max_documents=10)
|
|
for d in docs:
|
|
print(d["file_name"], d["character_count"])
|
|
# 只看前 300 字判断切题 ——— md_content 整体动辄几十 K(实测命中文档常 50K-200K 字符)
|
|
print((d["md_content"] or "")[:300])
|
|
```
|
|
|
|
```python
|
|
# 跨多个学科库联查(如同时找胶凝 + 陶瓷)
|
|
docs = search(
|
|
query="concrete carbonation",
|
|
kb_names=["mu_34_1740625285897", "mu_34_1740625303475"],
|
|
max_documents=6,
|
|
)
|
|
```
|
|
|
|
### `download(file_name, kb_name, working_dir, preview=False) -> str`
|
|
|
|
下载原始文档(PDF / Word / ...)到 `<working_dir>/documents/<safe_file_name>`,返回相对路径。已存在跳过下载直接复用。`file_name` 支持原始文件名(`example.pdf`)或 Markdown 名(`example.md`),server 自动回退。
|
|
|
|
```python
|
|
rel = download(
|
|
file_name="材料性能手册.pdf",
|
|
kb_name="mu_34_1740625285897",
|
|
working_dir=r"D:/projects/zcbot/workspace/users/<uid>/<wd>",
|
|
)
|
|
# rel == "documents/材料性能手册.pdf"
|
|
```
|
|
|
|
### `health() -> dict`
|
|
|
|
健康检查,公开端点(无需 API key)。主要给 smoke / 排障用:`{"status": "healthy", "service": "document_search_api"}`。
|
|
|
|
## 标准工作流
|
|
|
|
1. **(可选)`list_kb()`** —— 用户没指定库 / 不确定分类时看一下有哪些
|
|
2. **`search(query=..., max_documents=6)`** —— 中英文均可,专业技术术语优先英文
|
|
3. **看返回**:
|
|
- 用 `file_name + character_count + md_content[:300]` 判断切题
|
|
- 切题 → 直接用 `md_content` 给 LLM 引用(已结构化 Markdown,不需要再下载原件)
|
|
- 需要看图表 / 表格原貌 / 给用户附件 → `download(file_name, kb_name, working_dir)` 拿原文档,然后用主 agent 的 `read` 工具读(zcbot 已内置 PDF/Word 文本抽取)
|
|
4. **写产出**:把 md_content 关键段落引到申报书 / 方案里,标注来源文件名
|
|
|
|
## md_content 优先 vs 原件下载
|
|
|
|
- **绝大多数场景用 md_content 就够** —— API 已把原文档转成 Markdown,LLM 直接读,无需 OCR 或 PDF 抽取
|
|
- **仅以下场景下载原件**:
|
|
- 用户明说"要原文件"(给客户附件 / 存档 / 引用页码)
|
|
- md_content 里图表 / 表格 / 公式信息丢失(Markdown 转换无损不了)
|
|
- 文档过大(`character_count` > 10 万),想用 PDF reader 跳页抽取局部
|
|
|
|
## 错误处理
|
|
|
|
- `DOCUMENT_SEARCH_API_KEY` 未设:`RuntimeError`(client 启动时立即报,而不是裸 401)
|
|
- 401 / 403 `Invalid API key`:`httpx.HTTPStatusError` —— key 错或失效,告诉用户检查 env
|
|
- 404 `未找到知识库`:`kb_names` 拼写错或库已下线,改 `list_kb()` 看当前有效列表
|
|
- 404 `文件不存在: xxx`:`download` 时常见,可能 server 侧文件丢失或 `file_name` 拼写错
|
|
- search 命中 0 条:同义词 / 切换中英文 / 缩短 query / 放宽 `classification_ids` 再试 2-3 次,还是 0 条就明确告诉用户"本库没覆盖,改走 research 或换关键词",**不要凭训练数据脑补文献**
|
|
- 网络超时 / server 不可达:`httpx.ConnectError` / `httpx.TimeoutException` —— 告诉用户"document_search 暂时连不上",不要重试堆栈刷屏
|
|
|
|
## 反模式
|
|
|
|
- 用 `httpx` / `requests` 裸调 API(走 helper,免得 base_url / auth / 字段名漂移时四处改)
|
|
- `search(max_documents=20)` 一次拉满后 print 全部 `md_content`(单条就可能几十 K,20 条直接爆 LLM 上下文)—— 只 print `file_name + character_count + md_content[:300]`,要看全文用 `docs[i]['md_content']`
|
|
- 看到 md_content 切题还 `download` 一遍原件(md_content 已是 LLM 友好的 Markdown,大多数引用场景够用)
|
|
- 凭 `ch_name`("胶凝材料学科知识库")就以为 query 要用中文 —— 文档主体是英文,复杂术语用英文更精准
|
|
- 编造 file_name / kb_name —— 不在 `list_kb()` / `search` 返回里就**明确告诉用户"未命中"**,不要瞎传 ID
|
|
- 把 `download` 返回的相对路径当绝对路径用(它是相对 `working_dir` 的)
|
|
- 不在合适的 task working_dir 里 `download`(原文档应该落到 task 目录,不要污染 repo)
|