结论先行：RAG 数据管道不该只有一种交付形态。同一套解析→清洗→脱敏→切片→评测能力，可以用 CLI、HTTP 服务、FFI 动态库（C SDK）三种形态交付，分别适配脚本批处理、在线服务与嵌入式集成；形态选错，后期的运维与集成成本会成倍放大。
一、CLI：脚本与批处理
命令行工具 compressor 提供 preprocess / chunk / eval 等 RAG 命令加全套压缩命令，适合运维脚本、定时任务和一次性大批量入库。最典型的场景是财报季集中回补历史文档：把几百 GB 的存量 PDF、Word 丢给脚本分批跑，内容 SHA-256 幂等保证中断后重跑 0.2 秒即跳过已完成的预处理，大规模语料断点续跑、不返工。
它的边界也很清楚：CLI 本质是人触发、进程式，没有常驻服务与实时进度推送。凌晨批任务跑到一半失败，运维只能靠日志和退出码定位，问题往往第二天上班才被发现。所以它适合“批”的世界，不适合对外提供实时能力。
二、HTTP 服务：在线与集成
uglypear-server（基于 axum）提供同步/异步压缩、分块上传、批量、RAG 预处理、知识库、评测与管理后台，配合 SSE 进度推送与 Prometheus 监控。大文件分块上传不阻塞前端，处理进度实时可见；Prometheus 指标直接接进企业现有监控与告警体系，不用另起炉灶。接口行为有回归保障——12 项 HTTP API 测试与 6 个 SSE 事件流场景全部通过。
能力一旦暴露成 API，前端、内部平台与第三方应用都能接入，私有化部署也天然落在这个形态上：在客户内网起一个服务进程，全公司的系统按 API 调用即可，不必每台机器装一份工具、每个项目维护一套脚本，版本升级也只动服务端一处。
三、FFI 动态库：嵌入式
libcompressor.so 加 sdk.h 暴露 C API（rust_ingest_document / rust_resume_ingest 等），全部 catch_unwind 保护——Rust 层的 panic 不会外溢成宿主进程崩溃，这是嵌入商业软件的硬要求。28 项 SDK C API 测试覆盖主要调用路径，跨语言集成有据可依，Java、C#、Go 等语言通过 FFI 都能调用。
再往上一层是 Python SDK 与 LangChain 连接器（零依赖嵌入式客户端、元数据透传）。ISV 与数据平台用几行代码就能把解析与切片挂进 Dify、RAGFlow 或自研应用，不必每个项目重复搭一遍数据管道——这正是集成商客户最大的重复成本。
| 形态 | 适用 | 关键接口 |
|---|---|---|
| CLI | 批处理 / 脚本 | preprocess / chunk / eval |
| HTTP | 在线服务 / 集成 | SSE 推送 / Prometheus |
| FFI / SDK | 嵌入式 | rust_ingest_document 等 |
四、怎么选
一次性入库、定时任务选 CLI；对外提供检索问答服务选 HTTP；把能力嵌进自有软件选 FFI / Python SDK。判断依据归结为两个问题：谁来触发——人、调度系统还是宿主程序；结果给谁消费——文件目录、API 调用方还是上层应用。拿不准时从 HTTP 起步，它的兼容面最广，后续再按需下沉到 CLI 或 FFI。
三种形态共享同一套底层 crate（core / compressor / extractor / rag-*），行为一致——CLI 里验证过的切片参数，换到 HTTP 或 FFI 上结果相同，不会出现“测的是一套、上的是另一套”的漂移。
交付形态承接在完整数据流水线之后，先把流水线本身跑通，再按场景选形态。流水线设计见 文档解析流水线 与 切片策略；私有化落地见 私有化部署。
选型建议：四种交付形态的对照与组合
| 形态 | 典型使用者 | 关键能力 |
|---|---|---|
| CLI（compressor） | 数据工程师、一次性治理 | preprocess / chunk / eval 等 RAG 命令 + 全套压缩命令 |
| HTTP 服务（uglypear-server） | 平台团队、多消费者 | axum 实现，同步 / 异步、分块上传、SSE 进度推送、Prometheus 监控、管理后台 |
| FFI 动态库（libcompressor.so） | ISV 嵌入自有产品 | rust_ingest_document / rust_resume_ingest 等 C API，全部 catch_unwind 保护 |
| Python SDK + LangChain 连接器 | 算法工程师、原型验证 | 零依赖嵌入式客户端，元数据透传，可作 Dify / RAGFlow 数据入口 |
四种形态不是互斥选择，而是同一条流水线的不同入口：验证期用 SDK，生产期上 HTTP 服务，嵌入式产品走 FFI，运维脚本用 CLI。企业级配套（多租户 API Key、套餐配额、审计日志）在 HTTP 形态下最完整。选型的合规前提——部署形态与数据主权，见私有化部署与数据主权；从 SDK 起步的集成路径，见RAG 与微调怎么选。
常见问题 FAQ
Q1：RAG 数据管道有哪三种交付形态？
CLI（compressor 的 preprocess/chunk/eval）、HTTP 服务（uglypear-server，含 SSE 进度推送与 Prometheus 监控）、FFI 动态库加 Python SDK（libcompressor.so 的 C API）。三者共享同一套底层 crate，行为一致。
Q2：什么时候用 CLI？
一次性大批量入库、运维脚本、定时任务。CLI 本质是人触发、进程式，配合 SHA-256 幂等与断点续跑适合批量回补，重跑不返工，但不适合对外提供实时服务。
Q3：HTTP 服务有哪些能力？
同步/异步压缩、分块上传、批量、RAG 预处理、知识库、评测、管理后台，配 SSE 进度推送与 Prometheus 监控；12 项 HTTP API 测试与 6 个 SSE 场景全部通过，便于前端与应用集成。
Q4：嵌入式集成走哪条路？
libcompressor.so 加 sdk.h 的 C API（rust_ingest_document 等，全部 catch_unwind 保护，panic 不外溢），再加 Python SDK 与 LangChain 连接器，ISV 几行代码即可把管道嵌进自有产品。
需要搭建企业级 RAG 知识库？了解丑梨AI
私有化部署的 RAG 数据工程基座：解析、清洗、脱敏、压缩、切片、治理、评测一站式流水线，全本地推理，数据不出域，单机可部署。