后端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点击查看免费下载本指南以 xberg 仓库中的chunking-embeddings技能文档为核心骨架系统讲解 xberg 的文本分块Chunking与向量嵌入Embedding两大能力如何通过ExtractionConfig.chunking驱动分块、ChunkerType四类分块策略的差异、预设Preset如何同时决定分块大小与嵌入模型以及embeddings/static-embeddings/embedding-presets三个特性feature在构建与运行时的行为边界。读完本文你将掌握在配置文件与 Rust 代码中正确配置分块与嵌入、规避 serde 字段名与特性门控的常见陷阱、并把分块结果接入稠密/稀疏检索管线的完整实战方案。一、概览分块与嵌入在 xberg 中的位置xberg 的分块与嵌入实现分别位于 crates/xberg/src/chunking/27 个 Rust 文件与 crates/xberg/src/embeddings/含 ONNX 推理引擎engine与纯 Rust 的静态static_engine。这两个目录是完整模块而非单文件。分块由ExtractionConfig.chunking: OptionChunkingConfig驱动即分块总是发生在文本提取Extraction之后、向量化之前嵌入向量按chunk附加而不是按 document 附加见下文关键规则。二、分块入口两个公开 API 与数据结构2.1 两个独立入口通用入口chunking::chunk_text(text, ChunkingConfig, page_boundaries) - ResultChunkingResult定义于 chunking/core.rs。它是分块的主要公开 API支持纯文本与 Markdown可传可选的分页边界page_boundaries用于把块映射到页号。函数内部首先调用config.resolve_preset()解析预设再进入chunk_text_with_heading_source空文本直接返回空结果非空文本会先通过validate_utf8_boundaries校验 UTF-8 边界。RAG 专用入口chunking::rag::chunk_for_rag(text, ChunkingConfig)定义于 chunking/rag.rs。它是一个轻量组合器委托chunk_text完成切分但把默认的ChunkerType::Text自动升级为Markdown除非调用方已显式指定其他 chunker从而让分块感知标题层级并随后为每个 chunk 填充heading_path面包屑breadcrumb。2.2 返回结构ChunkingResult定义于 chunking/config.rspub struct ChunkingResult { pub chunks: Veccrate::types::Chunk, pub chunk_count: usize, }单个Chunk定义于 types/extraction.rs携带content块文本内容chunk_type由启发式分类器chunking/classifier.rs基于内容模式与标题上下文给出的语义结构分类默认UnknownmetadataChunkMetadata位置、页范围、标题路径等见下三个可选向量字段embedding稠密向量、sparse_embeddingSPLADE 稀疏向量、late_interactionColBERT 式多向量三者仅在对应配置与特性开启时填充且 serde 序列化时均skip_serializing_if Option::is_none。ChunkMetadata定义于 types/extraction.rs关键字段字段含义byte_start/byte_end块在原文中的字节区间UTF-8 合法边界token_count块内 token 数启用嵌入时由模型 tokenizer 计算chunk_index/total_chunks块序号与总数first_page/last_page块跨越的页号启用页追踪时填充1 起始heading_context使用 Markdown chunker 时的嵌套标题层级heading_path扁平化的标题路径根到本块的标题文本序列RAG 友好的面包屑image_indices本块覆盖页面上图片在顶层images集合中的索引三、ChunkerType只有这四种策略ChunkerType是唯一的切分策略枚举定义于 core/config/processing.rsserde 使用 lowercase 命名变体行为Text默认通用切分器按空白与标点切分不感知结构Markdown感知 Markdown 结构保留标题与代码块边界Yaml按 YAML 顶层键切分每个顶层键生成一个块Semantic主题感知切分见下文专节分块调度逻辑在 chunking/core.rsYaml转入yaml_section::chunk_yaml_by_sectionsSemantic转入semantic::chunk_semantic其余走text_splitter含TextSplitter与MarkdownSplitter。3.1 Semantic 切分嵌入感知与结构回退Semantic是唯一的理解内容的切分器实现在 chunking/semantic/mod.rs。其流程分两阶段先将文本按固定SEGMENT_SIZE 200字符切成细粒度片段有 Markdown 标题时用MarkdownSplitter否则TextSplitter检测主题边界并合并成块。有EmbeddingConfig时使用嵌入向量间的余弦相似度检测主题迁移阈值由topic_threshold控制默认0.75取值范围0.0..1.0值越低切出的块越多越小没有嵌入配置时回退到纯结构启发式detect_plain_text_boundaries全大写标题、编号章节、空行段落并把片段按max_characters默认 1000合并成组——此时topic_threshold完全不生效源码在warn_if_fallback_path中会给出警告。因此要发挥 Semantic 切分的最佳效果务必配对嵌入模型。四、ChunkingConfig字段、serde 线上名称与默认值ChunkingConfig定义于 core/config/processing.rs其核心字段与配置文件wire名称对照如下原技能文档的字段表经过源码核实字段配置文件中的 wire 名称默认值max_charactersmax_chars别名max_characters1000overlapmax_overlap别名overlap200trimtrimtruechunker_typechunker_typeTextpresetpreset无重命名是承重load-bearing的配置文件里写max_characters只有通过 alias 才能生效而拼写错误的键会被deny_unknown_fields之外的 serde 规则静默忽略详见 config-loading-precedence。此外还有几个源码新增、原文档未详列的字段embedding: OptionEmbeddingConfig为每个 chunk 生成稠密向量sparse_embedding: OptionSparseEmbeddingConfigSPLADE 稀疏向量需sparse-embeddings特性配置文件中才有此键无 CLI flag 与环境变量late_interaction: OptionLateInteractionConfigColBERT 多向量需late-interaction特性同上sizing: ChunkSizing块大小计量方式默认CharactersUnicode 字符数开启chunking-tokenizers特性后可选用Tokenizer { model, cache_dir }其中model可以是 HuggingFace tokenizer 模型 ID如Xenova/gpt-4o、bert-base-uncased或通过register_tokenizer_backend注册的后端名注册名优先topic_threshold: Optionf32见 Semantic 一节table_chunking: TableChunkingMode仅对Markdownchunker 生效默认Split超限表格按行切分续块无表头可选RepeatHeader每个续块重复预置表头与分隔行保证块自包含利于提取/搜索/LLM 消费。一个取自仓库契约 fixture 的真实配置示例fixtures/contract/chunking_config_and_output.json{ chunking: { max_characters: 300, overlap: 40, trim: true, chunker_type: text } }注意此处用的是 wire 名称chunker_type: textlowercase serde 名而非 Rust 枚举名。五、预设Preset同时决定块大小与嵌入模型ChunkingConfig.preset通过resolve_preset()解析实现在 core/config/processing.rs。它被#[cfg(feature embeddings)]门控没有embeddings特性时该函数被编译为 no-oppreset 名字什么都不做仅记录一条Chunking presets require the embeddings feature警告见 processing.rs。有特性时预设会覆盖max_characters与overlap并且若调用方没有显式提供EmbeddingConfig会顺带选定嵌入模型。预设真值来源是 embeddings/mod.rs 中的EMBEDDING_PRESETS静态表EmbeddingPreset结构还携带pooling、model_file、description、backend、additional_files、query_prefix等元数据。完整预设表预设chunk_sizeoverlap维度后端fast51250384ONNXbalanced1024100768ONNXquality20002001024ONNXmultilingual1024100768ONNXgte-modernbert-base1024100768ONNXlightweight51250256staticmodel2vecarctic-embed-m-v2.01024100768ONNXqwen3-embedding-0.6b20002001024ONNX源码补充了每个预设的底层细节均在EMBEDDING_PRESETS内所有 ONNX 预设的模型仓库均为xberg-io/embedding-models并固定在EMBEDDING_MODEL_REVISION提交4b127809f88a5aa1569d1238032b5ff40e5879bc下载时按EMBEDDING_SHA256_MANIFEST做 SHA-256 校验fast实为all-MiniLM-L6-v2的量化版~22M 参数mean 池化适合快速原型与资源受限环境balanced实为bge-base-en-v1.5~109M 参数cls 池化面向通用 RAG 与生产部署quality实为bge-large-en-v1.5~335M 参数cls 池化multilingual实为multilingual-e5-base100 语言mean 池化gte-modernbert-base为 2026 代 GTE ModernBERT base8192 长上下文cls 池化lightweight实为potion-base-8m~7.5M 参数走纯 Rust 的 model2vec 静态引擎EmbeddingBackend::Static是 WASM/Android 等no-ort-target上唯一可用的稠密嵌入arctic-embed-m-v2.0是 Snowflake Arctic-Embed-M v2.0非对称检索模型查询侧需预置query: 前缀query_prefix文档侧不做前缀其权重大文件存储在外部model.onnx.dataadditional_filesqwen3-embedding-0.6b是 decoder 式 last-token 池化的多语模型32k 上下文同样带外部数据文件。若 preset 名未识别resolve_preset()会记录Unknown chunking preset ...警告并原样返回配置不会报错中断。六、Embeddings模型选择与两个默认值不一致的坑6.1 不要写那些不存在的 API原技能文档明确告诫xberg没有TextEmbeddingManager、没有embed_chunks()、没有ChunkWithEmbedding、没有RagDocument也没有 fastembed 依赖。不要针对这些名字编写代码。6.2 EmbeddingModelType四种模型来源模型选择由EmbeddingModelTypetagged enumcore/config/processing.rs承载Preset { name }推荐直接引用上文预设表例如balancedCustom { model_id, dimensions }任意 HuggingFace ONNX 仓库如BAAI/bge-small-en-v1.5模型文件固定为model.onnxmean 池化Llm { llm: BoxLlmConfig }由 liter-llm 走 HTTP 提供商的托管嵌入如openai/text-embedding-3-small无本地模型下载Plugin { name }进程内注册的嵌入后端通过register_embedding_backend宿主语言负责模型生命周期无下载、无 ONNX Runtime 依赖此模式下仅normalize与max_embed_duration_secs生效batch_size/cache_dir/show_download_progress/acceleration均被忽略且 Semantic 切分在该模式下回退到max_characters作上限。6.3 两个默认值不一致且两者都真实生效这是最容易踩的坑之一EmbeddingModelType::default()返回gte-modernbert-base预设——语言绑定bindings与#[serde(default)]拿到的就是这个EmbeddingConfig::default()通过default_balanced_embedding_model()返回balanced预设processing.rs。两者在 processing.rs 中相邻定义却指向不同模型。因此在写代码前务必确认自己实际走的是哪个构造函数再判断最终运行的是哪个模型。6.4 EmbeddingConfig 默认值EmbeddingConfigprocessing.rs的默认值如下字段默认值normalizetrueL2 归一化为余弦相似度准备batch_size32max_embed_duration_secsSome(60)插件路径的调度超时防宿主后端挂死max_sequence_lengthNone回退到 512且最终被模型自身model_max_length封顶可设为长上下文模型值如 8192 让长块完整嵌入另有两个源码级扩展字段show_download_progress默认 false开启后模型/tokenizer/config 下载进度以info级日志输出到xberg::model_download目标与acceleration可选AccelerationConfig控制 CPU/CUDA/CoreML/TensorRT 执行提供者。6.5 推理引擎与缓存ONNX 路径由 embeddings/engine.rs 提供get_or_init_engine按仓库 模型文件 附加文件 修订 池化 最大序列长度 缓存根 加速配置构造缓存键EmbeddingEngineCacheKey模型文件与 tokenizer 首次下载后经ENGINE_CACHE复用embeddings/mod.rs。全局信号量限制并发 ONNX 推理调用防止大量异步调用耗尽资源Llm与Plugin变体在到达信号量前短路不占用本地推理资源池。七、特性门控与构建注意事项7.1 三个关键特性embeddings特性的依赖组合源码 embeddings/mod.rs 顶部注释与 Cargo 配置一致embeddings [onnx-runtime, dep:ndarray, chunking, tokio-runtime, embedding-presets]ort-bundled默认 ORT 链接方式会在构建时自动下载 ONNX Runtime——无需系统安装也不需要ORT_DYLIB_PATH。ORT_DYLIB_PATH仅在ort-dynamic链接方式下有意义动态加载系统 ORT 库。static-embeddings纯 Rust 的 model2vec 路径embeddings/static_engine.rs不依赖任何原生 ONNX 库是no-ort-targetWASM、Android x86_64 模拟器上唯一的稠密嵌入后端lightweight预设走的就是它。embedding-presets只携带预设元数据名称/尺寸/描述等WASM 安全。7.2 行为边界降级而非失败没有 ORT 的构建如 WASM 目标、未开static-embeddings应当跳过嵌入而非报错相关嵌入字段保持None分块照常进行。这要求特性组合可预测——preset在无embeddings特性时是惰性的语义切分在无嵌入时回退结构启发式都属于同一设计原则。八、heading_path 与三种检索臂的正确用法chunk_for_rag始终填充heading_path但分块器绝不把面包屑预置进chunk.contentcontent永远是源文档[byte_start, byte_end)的精确字节区间见 rag.rs 的 Breadcrumb placement 一节。面包屑的渲染是消费方在索引时的决定三种检索消费者需要三种不同的视图稠密/嵌入检索把render_heading_breadcrumb渲染出的# Guide ## Setup\n\n前缀拼进content再嵌入让段落自包含结构上下文嵌入质量更高词法检索BM25/TF-IDF面包屑有害——同一小节的所有块会重复相同的标题 token标题词的文档频率趋近块数IDF 塌缩到零。直接索引chunk.content原样即可或把heading_path作为单独的低权重字段无需剥离因为从未预置稀疏学习检索SPLADE比 BM25 更糟。SPLADE 的 term 权重来自通用语料训练的编码器看不到本集合统计无法自我纠偏且 term 展开会让标题词的整个学习邻域如Authentication→auth、login、credential、oauth…注入该节每个块整片语义区域判别力退化重索引也无法修复展开是预训练编码器的属性。永远不要喂面包屑给它。因此BM25 与 SPLADE 无需任何特殊处理按返回的 chunk 直接索引只有稠密臂需要显式多一步render_heading_breadcrumb。九、关键规则来自技能文档附源码印证先分块再嵌入——向量按 chunk 附加Chunk.embedding而非按 document单个文档的多个 chunk 各自携带向量。无embeddings特性的 preset 是惰性的——resolve_preset()被编译掉processing.rs。配置文件里写 serde wire 名称——max_chars/max_overlap或它们的别名max_characters/overlap而不是 Rust 字段名拼错键会被静默忽略。降级不要失败——无 ORT 的构建应跳过嵌入字段留None而不是报错。为余弦相似度归一化——normalize默认true保持开启。十、测试与契约佐证仓库测试直接验证了上述行为可作为实现事实的锚点tests/config_behavioral.rstest_chunking_max_chars_limits_chunk_size用max_characters: 100, overlap: 20分块 500 词文本断言每个 chunk 长度 100 20同文件test_chunking_overlap_creates_overlapconfig_behavioral.rs验证相邻块存在非空白重叠文本tests/config_loading_tests.rs 验证max_chars等 wire 名称从 TOML/JSON 配置正确加载tests/contract_mcp.rs 验证 MCP 请求中max_chars: 500正确映射到max_charactersfixtures/contract/chunking_config_and_output.json 给出端到端契约URI 输入 chunking 配置 →results[0].chunks至少 2 块且首个块内容长度 ≥ 9crates/xberg/tests/chunking_tokenizer_plugin.rs 覆盖Text/Markdown两种 chunker 与 tokenizer 插件路径。十一、Rust 实战示例将分块与嵌入接入提取管线的完整示例来自 embeddings/mod.rs 的文档示例use xberg::{extract, ChunkingConfig, EmbeddingConfig, ExtractInput, ExtractionConfig}; let config ExtractionConfig { chunking: Some(ChunkingConfig { preset: Some(balanced.to_string()), embedding: Some(EmbeddingConfig::default()), ..Default::default() }), ..Default::default() }; let output extract(ExtractInput::from_uri(document.pdf), config).await?; let result output.results.into_iter().next().expect(one input yields one result); for chunk in result.chunks.unwrap() { if let Some(embedding) chunk.embedding { println!(Chunk has {} dimension embedding, embedding.len()); } }注意EmbeddingConfig::default()的 model 实际是balanced预设见 6.3 节与preset: balanced一致若希望使用与EmbeddingModelType::default()相同的gte-modernbert-base需显式指定model。独立分块不经过提取管线则直接调用use xberg::chunking::{chunk_for_rag, ChunkingConfig, ChunkerType}; let markdown # Introduction\n\nWelcome.\n\n## Details\n\nMore text here.; let config ChunkingConfig { max_characters: 512, overlap: 50, chunker_type: ChunkerType::Markdown, ..Default::default() }; let result chunk_for_rag(markdown, config)?; for chunk in result.chunks { println!({:?} - {:?}, chunk.metadata.heading_path, chunk.content); }十二、关联技能分块与嵌入并不是孤岛它与以下仓库技能文档紧密联动遇到具体问题时建议对照阅读extraction-pipeline-patterns——分块之前的文本提取管线模式config-loading-precedence——ChunkingConfig的解析顺序与拼写错误静默忽略的原因feature-flag-policy——embeddings与static-embeddings、embedding-presets三者的边界与选择策略。赞分享后端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点击查看免费下载相关推荐embedding-strategies 实战指南为 RAG 与语义搜索选型、分块与评估嵌入模型embedding strategies 实战指南为 RAG 与语义搜索选型、分块与评估嵌入模型 本指南以 llm application dev 插件的 eAI 插件AI 技能开发工具claude-skills RAG Architect 实战Embedding 模型选型、微调与生产级嵌入流水线指南claude skills RAG Architect 实战Embedding 模型选型、微调与生产级嵌入流水线指南 Embedding嵌入向量是 RAGAI 技能AI 插件后端前端DevOpsLate Chunking 实战指南先嵌入整篇文档再切块的上下文保持型 RAG 策略all-rag-strategies 项目Late Chunking 实战指南先嵌入整篇文档再切块的上下文保持型 RAG 策略all rag strategies 项目 导读 Late Chunk示例工程上一篇从游戏回放到电影级镜头League Director 终极指南下一篇Office 装完就提示未激活LKY Office Tools 自动安装激活完整流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考