概述 #
启典后端提供基于 FastAPI 的 HTTP 接口，可用于把”保管期限判定””年度判定””扫描件提取””智能问答”等能力集成进其他业务系统（如档案管理系统、Excel 插件）。本指南合并了接口手册与调用说明，覆盖全部 7 个接口。
快速开始 #
启动 API 服务 #
cd Claw
python api_server.py启动后访问 http://localhost:8000/docs 查看 Swagger 在线文档，/redoc 查看 ReDoc 文档。
鉴权 #
所有接口需在请求头携带 API Key：
X-Api-Key: ytshuju-api-2026关闭鉴权：把 config.py 中的 API_SECRET_KEY 设为空字符串 "" 并重启服务。
接口总览 #
| 路径 | 方法 | 功能 | 是否上传文件 |
|---|---|---|---|
/health |
GET | 健康检查 | 否 |
/ask |
POST | 档案知识智能问答 | 否 |
/retention |
POST | 单条保管期限判定 | 否 |
/retention/batch |
POST | 批量保管期限判定 | 是（Excel） |
/year |
POST | 单条年度判定 | 否 |
/year/batch |
POST | 批量年度判定 | 是（Excel） |
/extract |
POST | 双层 PDF 元数据提取 | 是（PDF） |
接口详细说明 #
GET /health #
GET http://localhost:8000/health返回示例：{"status":"ok","mode":"local","model":"qwen3:32b"}
POST /ask #
{
"question": "合同原件应该保管多少年？",
"use_kb": true
}返回含 answer 与 sources（知识库检索原文片段）字段。
POST /retention（单条保管期限） #
{
"title": "关于2024年工作会议的通知",
"use_llm_fallback": true
}返回含 period（永久/30年/10年/待定）、method（rule/llm/unknown）、confidence。
POST /retention/batch（批量保管期限） #
multipart/form-data，键名 file，上传含”题名”列的 Excel，返回追加”保管期限””判定依据””判定方法”三列的 Excel。
curl -X POST "http://localhost:8000/retention/batch" \
-H "X-Api-Key: ytshuju-api-2026" \
-F "file=@titles.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"POST /year（单条年度判定） #
{
"title": "关于召开第三届代表大会的通知",
"signing_date": "20241120",
"closing_year": "2024"
}返回 year、method（签发日期/闭幕年/办结年/归档年度/未知需人工）等字段。判定优先级：闭幕年 > 办结年 > 签发日期 > 归档年度 > 未知需人工。
POST /year/batch（批量年度判定） #
multipart/form-data，键名 file，上传含”题名”和可选”签发日期”列的 Excel，返回追加”所属年度””年度判定说明””年度判定方法”三列。可选表单字段 archiving_year 统一传入整批归档年度。
POST /extract（双层 PDF 提取） #
multipart/form-data，键名 file，上传 PDF，返回 title / author / date / doc_num / confidence。仅支持双层 PDF，不支持纯扫描件、JPG、PNG。
调用示例（Python） #
import requests
BASE = "http://localhost:8000"
HEADERS = {"X-Api-Key": "ytshuju-api-2026"}
# 年度判定（单条）
resp = requests.post(f"{BASE}/year",
json={"title": "关于召开第三届代表大会的通知", "signing_date": "20241120", "closing_year": "2024"},
headers=HEADERS)
print(resp.json()) # {'title': '...', 'year': '2024', 'method': '闭幕年', ...}
# 批量年度判定
with open("records.xlsx", "rb") as f:
resp = requests.post(f"{BASE}/year/batch", files={"file": f},
data={"archiving_year": "2024"}, headers=HEADERS)
with open("year_result.xlsx", "wb") as out:
out.write(resp.content)错误码说明 #
| HTTP 状态码 | 含义 | 处理建议 |
|---|---|---|
| 200 | 成功 | — |
| 400 | 请求格式错误 / 文件格式不支持 | 检查参数或文件格式 |
| 401 | API Key 无效 | 检查 X-Api-Key 请求头 |
| 500 | 服务器内部错误 | 查看服务端日志（如 Ollama 未启动） |
注意事项 #
- PDF 要求：
/extract仅支持双层 PDF（含文字层）。 - 编码：所有 JSON 请求使用 UTF-8。
- 超时：涉及 LLM 的接口建议客户端超时 ≥ 60 秒。
- 并发：批量接口建议每批 ≤ 500 条。
- 知识库更新：文档更新后需重启 FastAPI 服务才能生效。
