278 lines
7.8 KiB
Markdown
278 lines
7.8 KiB
Markdown
# 档案导入 API
|
||
|
||
## 接口说明
|
||
|
||
导入一份 Markdown 档案文本，将其规范化为 Archive、Page、Chunk 三层结构，并为每个 chunk 生成全局唯一的 `chunk_uid`。
|
||
|
||
正式使用时，推荐直接上传原始 Markdown 文件，或者把 Markdown 原文作为请求体发送。系统会根据 Markdown 中的分页标记自动分页、分段和切 chunk。
|
||
|
||
导入会先写入 PostgreSQL。如果 `title/year/author/tags/summary` 缺失，系统会把 `archive_uid` 推入 Redis 队列，由独立的 `ai_metadata` process 异步请求 AI 补全并更新数据库。
|
||
|
||
当前版本会把导入结果保存为运行时快照文件：
|
||
|
||
```text
|
||
runtime/proofdb/imports/{import_uid}.json
|
||
```
|
||
|
||
后续接入 MySQL、OpenSearch、Vector DB 时，会沿用当前返回结构中的 UID。
|
||
|
||
## 请求方式
|
||
|
||
```http
|
||
POST /api/articles/import
|
||
```
|
||
|
||
支持三种调用方式：
|
||
|
||
1. `multipart/form-data` 上传 Markdown 文件。
|
||
2. `text/markdown` 或 `text/plain` 直接发送 Markdown 原文。
|
||
3. `application/json` 发送 Markdown 字符串，适合程序内部调用。
|
||
|
||
## 请求字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `file` | file | 否 | Markdown 文件。使用 `multipart/form-data` 时推荐传此字段 |
|
||
| `archive_uid` | string | 否 | 档案级 ULID。不传时系统自动生成 |
|
||
| `title` | string | 否 | 档案标题。不传时，系统会优先请求 AI 生成，失败后从 Markdown 标题或文件名推断 |
|
||
| `year` | int | 否 | 档案年份。不传时，系统会请求 AI 从文本中抽取或推断 |
|
||
| `author` | string | 否 | 作者或签发人。不传时，系统会请求 AI 从文本中抽取或推断 |
|
||
| `summary` | string | 否 | 档案摘要。不传时，系统会请求 AI 生成 |
|
||
| `source` | string | 否 | 来源标识。不传时，系统会使用上传文件名或 `raw-markdown` |
|
||
| `series` | string | 否 | 所属系列集 |
|
||
| `tags` | array | 否 | 标签数组。不传时，系统会请求 AI 生成 |
|
||
| `metadata` | object | 否 | 档案级元数据，例如年份、作者、馆藏信息 |
|
||
| `content` | string | 否 | Markdown 原文。JSON 调用时使用 |
|
||
| `pages` | array | 否 | 页数组。兼容字段，一般不需要调用方传入 |
|
||
| `pages[].page_number` | int|string | 是 | 页码，可传数字或原始页码字符串，例如 `12`、`12a`、`封面` |
|
||
| `pages[].content` | string | 是 | 当前页 OCR 或转录文本 |
|
||
| `pages[].metadata` | object | 否 | 页级元数据 |
|
||
| `paragraphs` | array | 否 | 段落数组。兼容字段，一般不需要调用方传入 |
|
||
| `paragraphs[].page_number` | int|string | 否 | 当前段落所在页码 |
|
||
| `paragraphs[].content` | string | 是 | 段落正文 |
|
||
| `paragraphs[].metadata` | object | 否 | 段落级元数据 |
|
||
| `chunk_size` | int | 否 | 每个 chunk 的目标最大字符数，默认 `800`，范围 `100-4000` |
|
||
| `chunk_overlap` | int | 否 | 超长文本硬切时的重叠字符数，默认 `120`，必须小于 `chunk_size` |
|
||
|
||
## Markdown 分页规则
|
||
|
||
系统会优先识别以下分页格式：
|
||
|
||
```markdown
|
||
<!-- DOCMASTER:PAGE 0001 -->
|
||
|
||
## Page 1
|
||
|
||
第一页正文...
|
||
|
||
---
|
||
|
||
<!-- DOCMASTER:PAGE 0002 -->
|
||
|
||
## Page 2
|
||
|
||
第二页正文...
|
||
```
|
||
|
||
如果没有 `DOCMASTER:PAGE` 标记，系统会把整份 Markdown 当作单页处理。
|
||
|
||
## 分段与 Chunk 切分策略
|
||
|
||
当前 import 使用 Markdown 预处理 + 页内向量 chunk 切分：
|
||
|
||
1. 先根据 Markdown 分页标记拆成 page。
|
||
2. 每页内部去掉分页标题、水平分隔线等结构性标记。
|
||
3. 页眉、页脚、密级、纯页码等噪声块会被过滤，不作为向量 chunk 的正文。
|
||
4. 检索证据只定位到页码，因此 chunk 可以跨段落、跨列表项，但不会跨页。
|
||
5. 每页内部会按段落/句子/自然停顿形成文本单元，并尽量打包到接近 `chunk_size`。
|
||
6. 如果单个文本单元超过 `chunk_size`，才退回固定字符窗口硬切，并使用 `chunk_overlap` 保留上下文。
|
||
|
||
## 请求示例
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8787/api/articles/import \
|
||
-F 'title=NSD 76 Disposition of NSC Policy Documents' \
|
||
-F 'source=archive://nsc/nsd-76' \
|
||
-F 'chunk_size=800' \
|
||
-F 'chunk_overlap=120' \
|
||
-F 'file=@test/1.test.md;type=text/markdown'
|
||
```
|
||
|
||
也可以直接发送 Markdown 原文：
|
||
|
||
```bash
|
||
curl -X POST 'http://127.0.0.1:8787/api/articles/import?title=NSD%2076&source=archive://nsc/nsd-76' \
|
||
-H 'Content-Type: text/markdown' \
|
||
--data-binary '@test/1.test.md'
|
||
```
|
||
|
||
JSON 调用示例：
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8787/api/articles/import \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{
|
||
"title": "NSD 76 Disposition of NSC Policy Documents",
|
||
"source": "archive://nsc/nsd-76",
|
||
"content": "<!-- DOCMASTER:PAGE 0001 -->\n\n## Page 1\n\nMarkdown 正文..."
|
||
}'
|
||
```
|
||
|
||
## 成功响应
|
||
|
||
状态码：
|
||
|
||
```http
|
||
201 Created
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "Archive imported.",
|
||
"data": {
|
||
"import_uid": "01HX8K7V9Y3QF2Z6M4A1B8C9D0",
|
||
"archive": {
|
||
"archive_uid": "01HX8K7V9Y3QF2Z6M4A1B8C9D0",
|
||
"title": "NSD 76 Disposition of NSC Policy Documents",
|
||
"year": 1992,
|
||
"author": "Brent Scowcroft",
|
||
"source": "archive://nsc/nsd-76",
|
||
"series": null,
|
||
"tags": [
|
||
"美国国家安全委员会",
|
||
"政策文件",
|
||
"NSD 76"
|
||
],
|
||
"summary": "这份档案是 1992 年关于 NSC 政策文件处置的国家安全指令，列明已被取代或已完成、不再有效的政策文件。",
|
||
"metadata": {
|
||
"ai_enrichment": {
|
||
"enabled": true,
|
||
"attempted": true,
|
||
"filled": [
|
||
"year",
|
||
"author",
|
||
"tags",
|
||
"summary"
|
||
],
|
||
"missing": [],
|
||
"model": "glm-4.7-flash"
|
||
}
|
||
}
|
||
},
|
||
"pages": [
|
||
{
|
||
"page_number": 1,
|
||
"block_count": 8,
|
||
"chunk_count": 2,
|
||
"content_length": 1042,
|
||
"chunk_uids": [
|
||
"01HX8K7V9Y3QF2Z6M4A1B8C9D0_1_28172",
|
||
"01HX8K7V9Y3QF2Z6M4A1B8C9D0_2_19304"
|
||
]
|
||
}
|
||
],
|
||
"chunks": [
|
||
{
|
||
"chunk_uid": "01HX8K7V9Y3QF2Z6M4A1B8C9D0_1_28172",
|
||
"chunk_index": 1,
|
||
"page_start": 1,
|
||
"page_end": 1,
|
||
"pages": [
|
||
1
|
||
],
|
||
"text": "NSD 45 20 AUG 90 U.S. Policy in Response to the Iraqi Invasion of Kuwait (C)\n* *COMMENT** OBE by operations Desert Shield and Desert Storm.",
|
||
"length": 142,
|
||
"embedding_ref": null
|
||
}
|
||
],
|
||
"stats": {
|
||
"page_count": 8,
|
||
"page_block_count": 86,
|
||
"chunk_count": 14,
|
||
"chunk_size": 800,
|
||
"chunk_overlap": 120
|
||
},
|
||
"queue": {
|
||
"ai_metadata_enqueued": true,
|
||
"needs_ai_metadata": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误响应
|
||
|
||
### JSON 格式错误
|
||
|
||
状态码：
|
||
|
||
```http
|
||
400 Bad Request
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "Invalid JSON body.",
|
||
"errors": {
|
||
"body": "Syntax error"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 参数校验失败
|
||
|
||
状态码：
|
||
|
||
```http
|
||
422 Unprocessable Entity
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 422,
|
||
"message": "Archive import validation failed.",
|
||
"errors": {
|
||
"source": [
|
||
"source is required."
|
||
],
|
||
"content": [
|
||
"content, file, pages, or paragraphs is required."
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 快照保存失败
|
||
|
||
状态码：
|
||
|
||
```http
|
||
500 Internal Server Error
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "Archive import snapshot could not be saved.",
|
||
"errors": {
|
||
"storage": "具体错误信息"
|
||
}
|
||
}
|
||
```
|
||
|
||
## UID 说明
|
||
|
||
| UID | 说明 |
|
||
| --- | --- |
|
||
| `import_uid` | 本次导入任务 ID，目前等同于档案级 ULID |
|
||
| `archive_uid` | 档案级 ULID，例如 `01HX8K7V9Y3QF2Z6M4A1B8C9D0` |
|
||
| `chunk_uid` | chunk 级核心 ID，格式为 `{archive_uid}_{chunk_index}_{short_uid}` |
|
||
|
||
`chunk_uid` 是后续 MySQL、OpenSearch、Vector DB 之间关联的核心字段。
|
||
|
||
`chunk_index` 从 `1` 开始递增。`short_uid` 是 5 位数字短码，由 chunk 的稳定内容哈希生成，方便人工查看和引用。
|