angineer-docs-core
AnGIneer 的文档解析入库引擎(纯 Python 库):把工程规范 / PDF / Office 文档跑成 「可读、可查、可算、可引用」的知识库数据——一条管线覆盖 源文件准备 → 格式转换 → MinerU 解析 → PoPo 强化 → 结构化 → 图描述 → SQLite+FTS → 向量索引 → 知识图谱, 外加五路检索、text2sql 与产物导出。
| 能力 | 说明 | 靠什么 |
|---|---|---|
| 📖 可读 | 高保真解析 PDF,保留结构、公式、图表 | MinerU 端点(HTTP) |
| 🔍 可查 | 语义检索 + 表格精确查询 + 条款定位(五路召回 + 重排) | canonical 七表 + qdrant |
| 🧮 可算 | 公式语义、表格插值、条款计算(供上层工具消费) | 结构化的 canonical 产物 |
| 📎 可引用 | 条文 / 表格 / 图片的块级溯源 | citation_targets + 块 id |
定位:只做数据面(解析 / 建索引 / 图谱 / 检索),不含网页端与管理台; 独立部署需要 HTTP 服务面时,可选装薄壳:
[server](只读检索面 retrieval-api,见下)、[api](解析面上传/续跑/产物下载,0.1.7 起,见下)。默认安装不含任何壳。 大算力全部在外部服务:版面解析、视觉结构强化、图描述、embedding、rerank 都走 HTTP 端点(配置见下)。
管线(9 个阶段 + 导出)
hard = 失败即中止;soft = 失败降级继续并在 parse_stages 留痕。
| # | 阶段 key | 名称 | 类型 | 依赖 | 做什么 |
|---|---|---|---|---|---|
| 1 | source_prep |
源文件准备 | hard | — | 落地源文件、登记文档节点、准备解析输入 |
| 2 | convert |
格式转换 | hard | source_prep | 非 PDF(doc/docx/xls…)经 LibreOffice 转 PDF |
| 3 | raw_parse |
MinerU 解析 | hard | convert | 调 MinerU 端点(file_parse ZIP 协议),产出 markdown / 图片 / middle.json |
| 4 | popo |
PoPo 强化 | soft | raw_parse | PoPo 做视觉结构强化,产出 enriched blocks(需 VLM 端点) |
| 5 | structure |
结构化 | hard | raw_parse | Solo 是唯一构建者;PoPo 信号只作为增强注入(对齐 / 合并 / 层级融合 / 续表) |
| 6 | figure_describe |
图描述 | soft | structure | VLM 描述图表内容(可关) |
| 7 | fts |
SQLite + FTS | hard | structure | canonical 七表 + 全文索引(检索数据面) |
| 8 | vectors |
向量索引 | soft | fts | qdrant(默认)/ sqlite / chroma |
| 9 | graph |
知识图谱 | soft | structure | 实体与关系抽取入库 |
第 10 步是产物导出(step10_export:按册导 markdown / 图片 / 索引 / 图谱)。
安装
pip install angineer-docs-core
# 或钉版本
pip install "angineer-docs-core @ git+https://github.com/0mao0/angineer-docs-core.git@v0.1.1"
Python 要求 >=3.10。运行依赖:angineer-tree-core(树表底座)、angineer-ai-inference(LLM 客户端)、
pydantic>=2、PyMuPDF、numpy、python-dateutil、qdrant-client、requests、python-dotenv。
可选 extras:[chroma](旧向量后端)、[text2sql](领域关键词 YAML)、[server](独立宿主薄壳 retrieval-api,见下)、[api](独立宿主薄壳解析面 docs-api,见下)。
另有外部依赖(不随包提供)
| 依赖 | 用途 | 怎么配 |
|---|---|---|
| MinerU 端点 | 版面解析(GPU 大头) | MINERU_CONFIGS |
| PoPo 端点 | 视觉结构强化 | POPO_CONFIGS |
| 图描述端点 | 图表描述 | FIGURE_DESCRIBE_CONFIGS |
| embedding 端点 | 向量化 | EMBEDDING_CONFIGS |
| rerank 端点 | 重排 | RERANKER_CONFIGS |
| Qdrant | 向量库(默认 provider) | QDRANT_URL(也可换 sqlite / chroma) |
| LibreOffice | 非 PDF → PDF | 系统安装,LIBREOFFICE_BIN 或 PATH |
快速开始
import os
os.environ["KNOWLEDGE_BASE_DIR"] = "/srv/knowledge" # 数据根(也可用 ANGINEER_DATA_ROOT)
os.environ["MINERU_CONFIGS"] = '[{"name":"dgx","url":"https://your-gateway/api/mineru","api_key":"..."}]'
os.environ["POPO_CONFIGS"] = '[{"name":"dgx","url":"https://your-gateway/api/popo/v1","api_key":"...","model":"Popo"}]'
os.environ["DOCS_VECTORSTORE_PROVIDER"] = "qdrant"
os.environ["QDRANT_URL"] = "http://localhost:6333"
from docs_core.parse_pipeline import ParseOrchestrator
orch = ParseOrchestrator() # 不注入时用包内置的解析记录表
doc_id = orch.ensure_document("default", "/abs/path/spec.pdf") # 登记文档节点
task = orch.create_parse_task("default", doc_id, "/abs/path/spec.pdf") # 后台线程跑全链
print(task["task_id"])
orch.get_parse_task(task["task_id"]) # 查进度 / 当前阶段
orch.cancel_parse_task(task["task_id"]) # 协作式取消
orch.retry_parse_task(doc_id) # 失败重跑
- 阶段级重跑与校验:
STAGE_REGISTRY/resolve_stage_order/validate_stage_retry/compute_resume_stages; - 检索侧入口:
docs_core.step09_query(五路召回 + 重排 + text2sql); - 知识库与节点管理:
docs_core.get_docs_service()/DocsService。
独立宿主壳(retrieval-api · [server] extra)
只读检索服务的最小形态——薄壳只保留对外验收面,数据面全参数化、无仓库树依赖:
pip install "angineer-docs-core[server]" # 只为此加装 fastapi/uvicorn
export ANGINEER_DATA_ROOT=/srv/angineer-data # 数据根(或 KNOWLEDGE_BASE_DIR)
export DOCS_VECTORSTORE_PROVIDER=qdrant
export QDRANT_URL=http://localhost:6333
export ANGINEER_API_TOKEN='...' # 可选:开启后除 /health 外要求 X-API-Key / Bearer
uvicorn docs_core.server:app --host 127.0.0.1 --port 8310
注(2026-10-13 外部消费方实踩补):env 必须由启动器注入子进程——壳不读进程 cwd 的
.env(包内load_dotenv()探测起点是包的安装目录,wheel 装在 site-packages 时碰不到你项目根的.env, 能否碰到随 venv 摆放而变、不可依赖)。漏注入可能表现为数据根 / 向量库解析失败(500)或能力静默 降级;启动后先核/health的 data_root / registry 两行。
| 端点 | 说明 |
|---|---|
POST /api/knowledge/internal/retrieve |
五路召回融合检索(snake_case 线契约,与主仓库内部服务逐位一致) |
POST /api/knowledge/internal/entity-search |
图谱实体检索 |
GET /api/knowledge/internal/doc-nodes |
文档节点清单(对话侧 load_nodes 数据源) |
POST /api/knowledge/internal/normalize-query · /internal/rerank · /internal/relevant-citations · /internal/table-blocks · /internal/engtool-run |
engine 端口 HTTP 面(条款号归一化 / phrase rerank / 引用挑选 / 表格块 / 外部工具执行)——chat 壳 http_ports 适配器消费;与主仓库 docs-api 同挂 |
GET /api/knowledge/libraries |
库清单 |
GET /api/knowledge/stats |
统计聚合(knowledge_stats 工具数据源;与主仓库 docs-api 同一实现) |
GET /api/knowledge/documents/{doc_id}/download |
原文回源(?kind=source|pdf、?disposition=inline 内联呈示) |
GET /health |
探活:数据根 / 注册表挂载状态 + 向量库配置形态 |
上传 / 解析 / 迁移 / 导出仍是库调用(ParseOrchestrator 等),不在检索壳内;解析走下面的解析面壳。
解析面壳(docs-api · [api] extra,0.1.7 起)
解析服务的最小形态——上传、断点续跑、状态轮询、产物下载。落盘与派生索引按 KB_STACK
档位(legacy=SQLite / pg=PostgreSQL+pgvector,与检索壳同一套 env);解析面写完派生层,
同 env 启动的检索面/编排面立即可检索引用,无需同步。
pip install "angineer-docs-core[api]"
export ANGINEER_DATA_ROOT=/srv/angineer-data # 数据根(文件层 + 派生索引都挂它下面)
export MINERU_CONFIGS='[{"name":"dgx","url":"https://your-gateway/api/mineru","api_key":"..."}]'
export KB_STACK=pg # 可选:PostgreSQL 档(配 KNOWLEDGE_PG_DSN)
export DOCS_API_STATIC_KEYS='key1,key2' # 静态 API Key(逗号分隔)
uvicorn docs_core.docs_api:app --host 127.0.0.1 --port 8312
- 鉴权:
/api/v1/*强制X-API-Key头;静态键命中即放行、视作未绑定库的键 (不注入也不限制library_id,调用方显式传库,不传落default)。 未配置DOCS_API_STATIC_KEYS时所有请求 401/403(与宿主无效键行为一致)。 - 就绪判定:
GET /health返回 200 +{service, started_at, pid, status}; 配置漂移或向量守卫异常时status=degraded并带config_errors——消费方按 body 判就绪,不是只看状态码。 - env 注入:与检索壳同口径——壳不读进程 cwd 的
.env,启动器必须显式注入子进程 env。 - 单实例守卫(可选):
python -m docs_core.docs_api入口 +DOCS_API_SINGLE_INSTANCE_GUARD=1启动前探/health拒绝重复启动;uvicorn直起不跑守卫(进程唯一性由调用方启动器保证)。
| 端点 | 说明 |
|---|---|
POST /api/v1/documents/parse?stages=all |
multipart file 上传解析;响应 {doc_id, task_id, status};stages=all 全链,也可传截断阶段(只产文件层,不写派生索引,属正常用法) |
POST /api/v1/documents/{doc_id}/resume |
断点续跑:已完成阶段保留;进行中 409 |
GET /api/v1/documents/{doc_id}/status |
{status, progress, stage, stage_message, error};status ∈ queued/processing/completed/failed/cancelled/partial |
GET /api/v1/documents/{doc_id}/artifacts |
{items:[{name,url}]};含 doc_blocks_graph.jsonl(+meta)、content.md、images.zip(有图时)等 |
GET /api/v1/documents/{doc_id}/artifacts/{name} |
产物字节流 |
GET /api/v1/documents/{doc_id}/pdf |
原始/转换后 PDF(输入即 PDF 时 404=用户已有源文件) |
GET /api/v1/documents/{doc_id}/blocks / /content |
块清单(页面/类型过滤)与 markdown 全文 |
DELETE /api/v1/documents/{doc_id} |
幂等软删:不存在返回 404,调用方按成功处理 |
GET /health |
探活(见上) |
解析面不提供:知识库管理面、用户/会话/键管理(宿主网页端诉求);R4 两点 PG 档结论见 CHANGELOG 0.1.7(FTS 落地方式 + 首连建表 DDL 覆盖范围)。
配置(常用)
| 变量 | 默认 | 说明 |
|---|---|---|
KNOWLEDGE_BASE_DIR |
— | 数据根(最高优先):元库 / 索引 / 图谱 / 文档目录都挂它下面 |
ANGINEER_DATA_ROOT |
— | 数据根(次优先,取 <root>/knowledge) |
ANGINEER_REPO_ROOT |
仓库标记探测 | 仓库树根。独立安装(wheel)里没有仓库树,需要数据根请显式给上面两个之一 |
MINERU_CONFIGS / POPO_CONFIGS / FIGURE_DESCRIBE_CONFIGS / EMBEDDING_CONFIGS / RERANKER_CONFIGS |
— | JSON 数组,顺序=优先级,第一项为默认;连接失败/超时自动切下一项 |
DOCS_VECTORSTORE_PROVIDER |
—(必填) | qdrant / sqlite / chroma;不设会直接报错(防静默连空库) |
QDRANT_URL |
— | provider=qdrant 时必填 |
LIBREOFFICE_BIN |
PATH 探测 | soffice 路径(非 PDF 输入必需) |
POPO_MAX_CONCURRENCY |
4 | PoPo 强化的并发闸(FIFO 排队) |
FIGURE_DESCRIBE_ENABLED |
见 .env.example |
图描述开关 |
包里包含什么
docs_core:管线与数据面本体(9 阶段、canonical 存储、五路检索、图谱、导出;docs_api/server薄壳随 extras);- PoPo 不随包(0.1.5 起 wheel 不再内嵌 popo fork):PoPo 视觉强化走独立客户端
popo-client(dgx-spark-popo 公开仓)或服务端文档级 API(POPO_CONFIGS); 缺失也不报错——第 4 步按「软阶段」跳过,结构由 Solo 单独构建(质量降级、链路不断)。 - 依赖
angineer-tree-core与angineer-ai-inference,pip 会自动带上。
目录结构
services/docs-core/
├── src/
│ ├── docs_core/
│ │ ├── paths.py # 布局:数据根 + 文档目录(纯路径计算,无 IO 副作用)
│ │ ├── docs_service.py # 门面:知识库/节点/任务落库与查询的统一入口
│ │ ├── parse_pipeline.py # 阶段注册 / 顺序 / 状态机 / 编排器
│ │ ├── models/ # 全管线共享契约(canonical 七表类型等)
│ │ ├── step01_source_prep/ # 源文件准备
│ │ ├── step02_convert2pdf/ # LibreOffice 转 PDF
│ │ ├── step03_mineru_parse/ # MinerU 解析 + PoPo 强化(popo_enhance)
│ │ ├── step04_structure/ # Solo 结构构建 + PoPo 信号消费(popo/ 六件套)
│ │ ├── step05_sqlite_fts/ # canonical SQLite + FTS(rebuild / store)
│ │ ├── step06_vectors/ # 向量索引(qdrant / sqlite / chroma + embedding 客户端)
│ │ ├── step07_graph/ # 知识图谱(实体 / 关系 / 证据包)
│ │ ├── step08_maintain/ # 巡检与维护
│ │ ├── step09_query/ # 检索(五路召回)、text2sql、对外协议
│ │ ├── step10_export/ # 产物导出
│ │ ├── docs_api/ # [api] 解析面薄壳(上传/续跑/产物/health,0.1.7 起)
│ │ └── library_registry.py / parse_records_store.py / kb_migrator.py …
├── tests/ # 88 个测试文件 / 500+ 用例
└── pyproject.toml
不在本库范围
- 网页端与管理台(主仓库 docs-api 宿主实现;
[server]/[api]extra 仅提供检索/解析两个薄壳); - MinerU / PoPo / VLM / embedding / rerank 的推理服务本身;
- 知识库数据的业务展示与权限。
开发与测试
pip install -e ".[dev]"
python -m pytest tests -q
独立环境(无仓库树、无 .env)也能跑:tests/conftest.py 会先按 dotenv 规则加载 .env(若有),
再补缺省 —— 向量后端用 sqlite、数据根指向临时目录;跨服务用例(需要 docs-api)自动跳过。
当前基线:516 passed, 16 skipped(无外部服务、无网络)。
许可
MIT
Metadata
Release files for angineer-docs-core 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| angineer_docs_core-0.1.8.tar.gz | 615.4 kB | With provenance | Details for angineer_docs_core-0.1.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| angineer_docs_core-0.1.8-py3-none-any.whl | Python 3 | none | any | Details for angineer_docs_core-0.1.8-py3-none-any.whl |
Total release size: 1.2 MB
Release files / angineer_docs_core-0.1.8.tar.gz
| Download URL | angineer_docs_core-0.1.8.tar.gz |
|---|---|
| Size | 615.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1ff997a8eceef5416e4eceac0f522eb86ab6fcfa1f1db0869142a286a09e5e21
|
|
BLAKE2b-256 checksum How to use checksums |
fac55d82217ca51221cf8c3dffa5f01f9f6a11c32b2ca30b122d6fe0f281d667
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / angineer_docs_core-0.1.8-py3-none-any.whl
| Download URL | angineer_docs_core-0.1.8-py3-none-any.whl |
|---|---|
| Size | 549.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd6fa69d6adc211fd49c14439ac973e8833831c3f9a14a5f6aab89dffa33cdef
|
|
BLAKE2b-256 checksum How to use checksums |
096e0f984d0cb0c65d8052084351ffdec6579c788ba83ff1c46392aad80155ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for angineer-docs-core 0.1.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for angineer_docs_core-0.1.8.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.