后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载surrealdb-xberg是 Xberg 文档提取管线与 SurrealDB 之间的官方 Python 集成包它负责自动建表、基于内容哈希的幂等去重、可选的文本分块与向量嵌入以及 BM25 / HNSW / RRF 索引配置。读完本篇你可以用不到 20 行 Python 代码把整个文档目录PDF、DOCX 等抽取入库并立即获得全文检索、语义检索和混合检索三种查询能力。工作原理提取 → 连接 → 存储 → 检索整条管线可以概括为四个阶段Extract提取—— Xberg 解析源文档需要时对扫描版执行 OCR并可顺带产出关键词、NER 实体、表格、摘要与质量分。Connect连接—— 连接器接收提取结果并管理 SurrealDB 异步连接连接、会话或事务对象均可。Store存储—— 每个文档的内容计算 SHA-256 哈希用于去重可选地分块并生成嵌入向量然后写入自动生成的 schema。Search检索—— 入库完成后即可使用全文检索BM25、向量检索HNSW和混合检索RRF 融合。这一流程在源码中对应清晰的调用链BaseIngester 实现了四个ingest_*入口先调用 Xberg 的extract/extract_batch再由子类的_ingest_batch把文档映射为数据库行并执行INSERT IGNORE。安装与环境准备pip install surrealdb-xberg要求Python 3.10并且需要一台运行中的 SurrealDB 实例。当前仓库中 pyproject.toml 声明的运行时依赖为anyio4,5、xberg1.2.8,2、surrealdb2.0.0,3包版本为 1.2.8MIT 协议。用 Docker 快速拉起一个本地 SurrealDBdocker run --rm -p 8000:8000 surrealdb/surrealdb:latest start --allow-all --user root --pass root注意文档中的--allow-all适用于本地开发。生产环境应使用--user/--pass加上最小权限并通过use指定独立的 namespace/database。连接侧使用官方surrealdbPython SDK 的异步客户端所有示例统一采用如下模式见 examples/README.mdfrom surrealdb import AsyncSurreal async with AsyncSurreal(ws://localhost:8000) as db: await db.signin({username: root, password: root}) await db.use(default, default)db可以是任意实现了query()的异步对象——AsyncSurreal连接、事务或会话均满足 AsyncSurrealQueryable 协议这意味着你既可以在独立事务中跑整批入库也可以直接复用应用已有的连接。快速上手最小可用路径只有三步——建 schema、按 glob 扫描目录入库之后即可查询from surrealdb_xberg import DocumentPipeline pipeline DocumentPipeline(dbdb, embedTrue, embedding_modelbalanced) await pipeline.setup_schema() await pipeline.ingest_directory(./papers, glob**/*.pdf)完整的向量检索流程如下摘自 README 快速示例import asyncio from surrealdb import AsyncSurreal from surrealdb_xberg import DocumentPipeline async def main() - None: async with AsyncSurreal(ws://localhost:8000) as db: await db.signin({username: root, password: root}) await db.use(app, docs) pipeline DocumentPipeline(dbdb, embedTrue, embedding_modelbalanced) await pipeline.setup_schema() # 先探测向量维度再创建表与索引 # 整个目录只发起一次 extract_batch然后分批幂等插入 await pipeline.ingest_directory(./papers, glob**/*.pdf) # 对 chunks 表做向量检索 embedding await pipeline.embed_query(retrieval augmented generation) hits await pipeline.client.query( fSELECT document.source AS source, content, vector::distance::knn() AS distance fFROM {pipeline.chunk_table} WHERE embedding |5,COSINE| $embedding ORDER BY distance, {embedding: embedding}, ) print(hits) asyncio.run(main())选择入口类DocumentConnector 还是 DocumentPipeline包提供两个入口点选择依据是“是否需要分块与嵌入”DocumentConnectorDocumentPipelineDocumentPipeline(embedFalse)存储对象整篇文档文档 分块chunks文档 分块chunks嵌入向量无有可配置模型与维度无索引文档上的 BM25chunks 上的 BM25 HNSWchunks 上的 BM25适用场景整篇文档的关键词检索分块上的语义检索 / 混合检索分块上的关键词检索两者的分工在源码中一目了然DocumentConnector 只做“整篇文档 BM25”_ingest_batch将全部文档行合并为一次INSERT IGNOREDocumentPipeline 额外维护chunk_table默认chunks把每个Chunk展开为带父文档 record link 的行并在启用嵌入时创建 HNSW 索引。两者都是全异步 API接受任意异步 SurrealDB 连接、会话或事务。入库入口四种粒度的幂等写入所有入口都遵循同一条路径经 Xberg 提取 → 确定性 record ID INSERT IGNORE幂等写入。重复摄取相同内容是 no-op。await pipeline.ingest_file(report.pdf) # 单文件 await pipeline.ingest_files([a.pdf, b.docx]) # 多个文件单次批量 extract_batch await pipeline.ingest_directory(./corpus, glob**/*.pdf) # 目录 glob默认 **/* await pipeline.ingest_bytes(dataraw, mime_typeapplication/pdf, sourceupload://1) # 原始字节几个值得注意的实现细节见 BaseIngester批量提取避免 N1ingest_files/ingest_directory把所有文件读入内存后只调用一次extract_batch失败的输入通过_pair_documents按index对齐剔除保证幸存文档与来源标识source一一对应。本地文件走 bytes 而非file://URI_input_from_path把文件读成字节并推断 MIME猜不到时回退application/octet-streamXberg 会自行做内容嗅探从而绕开 Xberg 对本地文件 URI 的显式允许开关。确定性去重键文档行 ID 为RecordID(table, sha256(content))chunk 行 ID 为{content_hash}_{index}见 _content_hash 与 _build_chunk_records。同一内容无论摄取多少次、在哪个目录都会命中同一行。批内再分批DocumentPipeline构造参数insert_batch_size默认 100控制每批INSERT IGNORE的最大记录数用于在吞吐量与内存占用之间取得平衡。若未先调用setup_schema()就发起入库会抛出SchemaNotInitializedError见 exceptions.py。增量摄取的行为可以用 examples/incremental_ingest.py 直接验证首次摄取插入全部文档与分块再次摄取时被INSERT IGNORE跳过新增文件时只写入新内容。Schema 自动管理setup_schema 的完整参数setup_schema()会自动创建 analyzer、表、字段与索引无需手写任何 DDL。DDL 由 schema.py 中的纯函数生成全部语句带IF NOT EXISTS可重复执行。DocumentPipeline.setup_schema 参数await pipeline.setup_schema( analyzer_languageenglish, # BM25 analyzer 的 Snowball 词干化语言 bm25_k11.2, # BM25 词频饱和参数 bm25_b0.75, # BM25 文档长度归一化参数 distance_metricCOSINE, # HNSW 距离函数如 COSINE、EUCLIDEAN hnsw_efc150, # 构建期搜索宽度越大建得越慢、召回越好 hnsw_m12, # 每个节点最大边数越大越占内存、召回越好 )生成的 DDL 骨架build_pipeline_schema大致为DEFINE ANALYZER IF NOT EXISTS doc_analyzer TOKENIZERS class FILTERS snowball(english); DEFINE TABLE IF NOT EXISTS documents SCHEMAFULL; -- source / content / mime_type / title / authors / created_at / metadata(FLEXIBLE) -- quality_score / content_hash / detected_languages / keywords / summary / entities / tables DEFINE INDEX IF NOT EXISTS idx_doc_source ON TABLE documents FIELDS source UNIQUE; DEFINE INDEX IF NOT EXISTS idx_doc_hash ON TABLE documents FIELDS content_hash UNIQUE; DEFINE TABLE IF NOT EXISTS chunks SCHEMAFULL; -- document(recorddocuments) / content / chunk_index / embedding / page_number -- char_start / char_end / word_count / first_page / last_page DEFINE INDEX IF NOT EXISTS idx_chunk_content ON TABLE chunks FIELDS content FULLTEXT ANALYZER doc_analyzer BM25(1.2,0.75) HIGHLIGHTS; -- 仅当 embedTrue 时 DEFINE INDEX IF NOT EXISTS idx_chunk_embedding ON TABLE chunks FIELDS embedding HNSW DIMENSION probed TYPE F32 DIST COSINE EFC 150 M 12;DocumentConnector.setup_schema只有前三个参数analyzer_language、bm25_k1、bm25_b且 BM25 索引建在documents.content上见 build_connector_schema。向量维度的自动探测如果构造DocumentPipeline时未显式指定embedding_dimensionssetup_schema会先做一次探针把一段短文本embedding dimension probe送进 Xberg 提取管线取len(chunk.embedding)作为 HNSW 的DIMENSION见 _probe_embedding_dimensions。已知维度时可直接传embedding_dimensions1024跳过探针。存储的数据模型不止是文本每个文档行携带的字段documents 表 DDL 与 _map_result_to_doc字段说明source来源标识文件路径或自定义 ID唯一索引content/mime_type抽取出的全文与 MIME 类型title/authors/created_at元数据核心字段metadata灵活对象subject、keywords、language、tags、additional 等quality_scoreXberg 的内容质量分content_hashSHA-256 哈希唯一索引兼作去重键detected_languages检测到的语言列表keywords提取的关键词文本列表summary摘要若启用 summarizationentitiesNER 结果category/text/start/end/confidence作为一等列便于图查询tables表格markdown/page_number/cellsDocumentPipeline额外写入chunks表每行通过documentrecord link 指回父文档携带content、chunk_index、页码/字节偏移first_page/last_page/char_start/char_end、word_count以及启用嵌入时embedding。chunk→document 的链接聚合、兄弟分块导航等模式可在 examples/chunk_explorer.py 中查看。检索实战BM25、向量与混合RRFexamples/search_patterns.py 是一个可运行的交互式脚本演示入库后立即可用的三种检索模式uv run python examples/search_patterns.py path-to-directory1. BM25 全文检索带高亮——利用FULLTEXT ... HIGHLIGHTS索引bm25 await pipeline.client.query( fSELECT document.source AS source, search::score(1) AS score, fsearch::highlight(, , 1) AS highlight fFROM {ct} WHERE content 1 $query fORDER BY score DESC LIMIT $limit, {query: query, limit: LIMIT}, )2. 向量语义检索HNSW 余弦距离——查询文本先经embed_query()复用入库时的嵌入配置embedding await pipeline.embed_query(query) vector await pipeline.client.query( fSELECT document.source AS source, content, vector::distance::knn() AS distance fFROM {ct} WHERE embedding |{LIMIT},COSINE| $embedding fORDER BY distance, {embedding: embedding}, )3. 混合检索RRF 融合——用search::rrf把两路结果按排名倒数融合倒数排名常数 60hybrid await pipeline.client.query( fSELECT * FROM search::rrf([ f(SELECT id, content, document.source AS source FROM {ct} f WHERE embedding |{LIMIT},COSINE| $embedding), f(SELECT id, content, document.source AS source, search::score(1) AS score FROM {ct} fWHERE content 1 $query ORDER BY score DESC LIMIT {LIMIT}) f], {LIMIT}, 60);, {embedding: embedding, query: query}, )抽取行为控制传入 ExtractionConfig两个入口类都接受 Xberg 的ExtractionConfig用于开启 OCR、关键词、NER、摘要与分块from xberg import ExtractionConfig, NerConfig, SummarizationConfig config ExtractionConfig(nerNerConfig(), summarizationSummarizationConfig()) connector DocumentConnector(dbdb, configconfig)DocumentPipeline对ChunkingConfig有一个巧妙约定见 _build_extraction_config它会把自己的嵌入配置注入到你提供的ChunkingConfig中或创建一个默认配置同时保留你设置的max_characters/overlap/preset。由于ExtractionConfig与ChunkingConfig都是 frozen dataclass这一过程通过dataclasses.replace完成不会修改你传入的原始对象embedFalse时注入的embedding为None即只分块不算向量。错误处理与平台限制入库失败不会被静默吞掉。_execute_insert 同时覆盖两种失败形态SurrealDB 2.0 SDK 对status: ERR直接抛出结构化ServerError部分引擎会把错误吞进INSERT IGNORE的返回结果列表返回错误字符串而非异常此时_check_insert_result会扫描结果并补抛异常。三类异常exceptions.py异常触发场景SchemaNotInitializedError未调用setup_schema()就发起入库IngestionError任意INSERT IGNORE静默失败含服务器错误DimensionMismatchError向量维度与已有 HNSW 索引冲突继承自IngestionError平台级限制重要SurrealDB v3 的 HNSW 维度约束是服务器全局的——只要某处存在维度 N 的 HNSW 索引之后任何 namespace / database 中插入不同维度的向量都会失败。因此同一台 SurrealDB 上所有管线应使用同一嵌入模型或拆分为独立实例。触发冲突时你会收到信息明确的DimensionMismatchError而不是面对一张空表。测试与进一步阅读本集成包自带完整测试单元测试覆盖 schema 生成test_schema.py、批量/去重/错误归一化test_base.py、两个入口类的行为test_connector.py/test_pipeline.pytest_integration.py标记了integration用例需要真实 SurrealDB 实例运行pytest -m integration才会执行见 pyproject.toml 中的 marker 定义。关键源码路径索引包入口与导出src/surrealdb_xberg/__init__.py整篇文档连接器src/surrealdb_xberg/connector.py分块 嵌入管线src/surrealdb_xberg/pipeline.py共享摄取基类与幂等插入src/surrealdb_xberg/_base.pyDDL 生成src/surrealdb_xberg/schema.py可运行示例单文档入库 / 三种检索 / 分块遍历 / 增量去重examples/包级 README含全部 API 速览integrations/python/surrealdb/README.md总结一下选型决策只要整篇文档的关键词检索用DocumentConnector要分块级语义/混合检索典型 RAG用默认配置的DocumentPipeline要分块但不上向量用DocumentPipeline(embedFalse)。三条路径共享同一套幂等摄取与 schema 管理可以按检索需求渐进升级而不用重写入库逻辑。赞分享后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载相关推荐OSXCollector部署最佳实践安全高效的企业级方案 OSXCollector部署最佳实践安全高效的企业级方案 在当今数字化时代 macOS取证工具 已成为企业安全团队不可或缺的利器。 OSXCollec后端AI 应用NLPNiceGUI 使用指南用纯 Python 快速构建 Web 用户界面NiceGUI 使用指南用纯 Python 快速构建 Web 用户界面 NiceGUI 是一个易用的、基于 Python 的 UI 框架界面直接呈现在 We后端AI 应用NLPXberg C FFI 实战用 xberg_extract 从远程 URL 提取文本文档Xberg C FFI 实战用 xberg_extract 从远程 URL 提取文本文档 本文以 Xberg 仓库中自动生成的 C 语言 E2E 片段 url后端AI 应用NLP上一篇数据科学场景设计实战Data-Science-For-Beginners 作业的「采集—存储—洞见—决策」四步法解析下一篇使用 Codex Skill 自动化 HTML 转图片基于 Rube MCP 与 Composio Html To Image 工具箱的完整实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考