参考资料

• FastAPI documentation
• LangChain documentation
• LangGraph documentation
• OpenTelemetry documentation
• Kubernetes documentation

生产工程（13） - 附录：常用库和框架

这份清单按工程职责组织工具，而不是按流行度罗列名称。 选型前先写清数据规模、延迟目标、部署边界、团队能力和退出方案。 框架可以减少胶水代码，但不能替代对请求链路、数据契约和失败边界的理解。

一、Web API 与数据契约

1.1 FastAPI

• 职责：用 Python 构建 HTTP API，并从类型声明生成请求校验和 OpenAPI 文档。
• 适用：Python 模型服务、RAG 后端和需要异步 I/O 的轻量 API。
• 不解决：任务队列、数据库迁移、鉴权策略和生产进程管理仍需单独设计。
• 验收：校验 2xx、4xx、5xx、超时和客户端取消，不只打开 Swagger 页面。

1.2 Uvicorn

• 职责：运行 ASGI 应用的服务器，负责事件循环、连接和协议处理。
• 适用：本地开发或作为生产部署进程的一部分。
• 不解决：多实例调度、TLS、全局限流和故障转移通常由外围基础设施负责。
• 验收：检查 worker、优雅关闭、keep-alive、反向代理头和健康探针。

1.3 Pydantic

• 职责：把外部数据解析为类型模型，并执行字段级结构校验。
• 适用：请求响应、工具参数、配置和结构化模型输出。
• 不解决：字段类型正确不等于业务允许，权限和状态约束仍由业务层判断。
• 验收：覆盖缺失字段、额外字段、枚举、边界值和错误路径。

1.4 httpx

• 职责：提供同步与异步 HTTP 客户端，用于调用模型和其他服务。
• 适用：需要连接池、超时分段、流式响应或异步并发的 Python 应用。
• 不解决：重试、熔断、幂等和请求签名需要按上游契约配置。
• 验收：模拟连接失败、读超时、限流和流式中断，确认资源被释放。

二、模型接入

2.1 模型服务商 SDK

• 职责：封装认证、请求类型、流式事件和服务商特有能力。
• 适用：明确绑定某个服务商，并需要其最新工具调用或结构化输出能力。
• 不解决：跨服务商字段、错误码、Token 统计和能力并不完全兼容。
• 验收：固定 SDK 与模型版本，保存原始错误和结束原因。

2.2 OpenAI 兼容客户端

• 职责：通过相似的 HTTP 契约连接云端或本地兼容模型服务。
• 适用：内部网关、vLLM 等实现了目标接口子集的服务。
• 不解决：“兼容”不代表所有模型、流式事件和工具字段完全一致。
• 验收：针对实际服务探测模型列表、流式、工具调用和错误响应。

2.3 LiteLLM

• 职责：统一多模型调用接口，并可提供代理、路由、预算和观测能力。
• 适用：确实需要多服务商切换或集中管理调用策略的团队。
• 不解决：抽象层不能消除模型能力差异，路由也不能自动保证质量等价。
• 验收：比较直连与代理的字段、延迟、错误映射、成本和降级结果。

2.4 vLLM

• 职责：为自托管语言模型提供高吞吐推理服务。
• 适用：有 GPU 运维能力、模型许可清晰且流量规模能支撑自部署成本。
• 不解决：模型质量、容量规划、安全更新和故障恢复仍由平台负责。
• 验收：测量 TTFT、TPOT、并发、显存、队列、错误率和模型质量。

三、LLM 应用编排

3.1 LangChain

• 职责：用 Runnable 等接口组合 Prompt、模型、解析器、Retriever 和 Tool。
• 适用：需要统一调用约定、流式传递和可替换组件的应用层代码。
• 不解决：引入框架不会自动产生正确架构，也不会替代业务状态模型。
• 验收：为每个 Runnable 固定输入输出类型，并测试异常如何沿 chain 传播。

3.2 LangGraph

• 职责：用图、状态和检查点表达可暂停、恢复、分支的 Agent 或 Workflow。
• 适用：多步任务需要持久化状态、人工介入或失败恢复。
• 不解决：节点副作用仍要幂等，状态 Schema 与迁移仍需业务设计。
• 验收：覆盖分支、循环上限、中断、恢复、重复事件和检查点版本。

3.3 LlamaIndex

• 职责：提供数据连接、索引、检索和查询编排组件。
• 适用：知识数据接入种类多，需要快速组合检索链路的项目。
• 不解决：默认解析与切分不一定适合企业文档，权限过滤必须显式验证。
• 验收：把每个候选回链到原文位置，离线比较召回和引用质量。

3.4 Dify

• 职责：通过可视化界面配置模型、知识库、工作流和应用发布。
• 适用：需要快速验证业务流程或让非开发角色共同维护编排。
• 不解决：低代码不等于无运维，平台升级、数据归属和扩展边界要提前确认。
• 验收：导出配置，验证权限、版本、错误分支、日志和迁移方案。

3.5 Coze

• 职责：提供 Bot、插件、知识库和工作流等托管能力。
• 适用：目标渠道与平台能力匹配，且可以接受相应托管边界的场景。
• 不解决：平台能力、区域、配额和数据政策可能约束后续迁移。
• 验收：先验证发布渠道、身份传递、插件权限、日志可见性和数据导出。

四、文档解析与检索

4.1 Unstructured

• 职责：把多种文档格式解析为带类型和 metadata 的内容元素。
• 适用：PDF、Office、HTML 等异构资料的摄取管线。
• 不解决：复杂表格、扫描件、阅读顺序和版面语义仍可能解析错误。
• 验收：抽样对照原文页码、标题层级、表格单元格和图片占位。

4.2 Chroma

• 职责：提供向量保存、metadata 过滤和相似检索能力。
• 适用：本地实验、原型和数据规模较小的知识库。
• 不解决：生产高可用、备份、权限隔离和大规模容量要单独评估。
• 验收：测试持久化、删除、更新、过滤、重建和并发访问。

4.3 pgvector

• 职责：在 PostgreSQL 中保存向量并执行相似度查询。
• 适用：已有 PostgreSQL，数据规模和性能目标允许统一存储的团队。
• 不解决：索引参数、查询规划和高维数据成本仍需要数据库调优。
• 验收：用真实数据执行 EXPLAIN，测召回、延迟、过滤和索引重建。

4.4 Milvus

• 职责：面向较大规模向量数据提供索引、检索和分布式能力。
• 适用：向量规模、吞吐或隔离需求超过单机轻量方案的场景。
• 不解决：引入分布式系统会增加容量、升级、备份和一致性运维成本。
• 验收：压测写入、查询、过滤、扩缩容、节点故障和备份恢复。

4.5 Elasticsearch

• 职责：提供全文检索、BM25、过滤、聚合和向量检索能力。
• 适用：精确词、复杂过滤和语义召回需要组合的搜索系统。
• 不解决：字段映射、分词器和相关性参数错误会直接降低召回质量。
• 验收：保留查询 DSL、explain 结果、各路候选、融合排名和延迟。

4.6 Neo4j

• 职责：存储实体关系并执行图查询，支持显式多跳关系检索。
• 适用：问题依赖关系路径，且实体、边和约束可以可靠抽取的场景。
• 不解决：把文本转成图的质量、实体消歧和图更新成本不会自动消失。
• 验收：核对实体来源、关系证据、查询路径、缺边和越权遍历。

五、任务与状态基础设施

5.1 Redis

• 职责：提供缓存、限流计数、短期状态和部分队列能力。
• 适用：可重建数据、低延迟访问和有明确过期策略的状态。
• 不解决：缓存不能作为所有业务事实的唯一来源，持久性取决于具体配置。
• 验收：测试 Key 范围、TTL、穿透、击穿、淘汰和故障恢复。

5.2 Celery

• 职责：在 Python 应用中分发和执行异步任务。
• 适用：文档解析、批量 Embedding、离线评测等不要求同步完成的任务。
• 不解决：至少一次投递可能导致重复执行，任务必须设计幂等。
• 验收：覆盖重试、超时、重复投递、worker 中断、死信和结果追踪。

5.3 Kafka

• 职责：以持久化日志传递事件，并支持消费者组和回放。
• 适用：需要解耦生产消费、保留事件历史和横向扩展的链路。
• 不解决：消息顺序、重复消费、Schema 演进和最终一致性要由系统设计。
• 验收：验证分区键、消费位点、重复事件、积压、重放和兼容性。

六、评测与观测

6.1 pytest

• 职责：组织 Python 单元、集成和参数化测试。
• 适用：确定性业务逻辑、解析器、检索组件和 API 契约测试。
• 不解决：测试框架不会自动定义 AI 输出的质量标准。
• 验收：固定随机性和数据版本，失败时输出最小样本与完整断言差异。

6.2 Playwright

• 职责：在真实浏览器中自动化用户交互和页面断言。
• 适用：流式回答、取消、引用、错误提示和跨页面工作流验收。
• 不解决：端到端测试成本较高，不应替代更快的单元和接口测试。
• 验收：桌面和移动端覆盖成功、慢响应、中断、4xx 与 5xx。

6.3 Ragas

• 职责：为 RAG 链路提供一组可组合的评测思路和指标实现。
• 适用：有可解释数据集并愿意校准指标与人工判断的团队。
• 不解决：默认指标不一定等于业务成功，也可能受评审模型偏差影响。
• 验收：保存逐样本得分，抽样人工复核，并监控指标版本变化。

6.4 Langfuse

• 职责：记录 LLM Trace、Prompt、反馈、评测和成本等观测数据。
• 适用：需要跨请求定位链路、比较 Prompt 版本和建立数据集的系统。
• 不解决：接入平台不等于自动获得正确埋点，敏感字段必须先治理。
• 验收：确认 Trace 关联完整、采样可解释、数据脱敏和保留周期明确。

6.5 OpenTelemetry

• 职责：用统一语义记录 Trace、Metric 和 Log，并传输到观测后端。
• 适用：需要把 AI 调用与 Web、数据库、队列和外部服务串成全链路。
• 不解决：自动埋点通常缺少业务质量、Prompt 版本和知识版本字段。
• 验收：验证 span 父子关系、上下文传播、错误状态、采样和脱敏。

七、部署与资产

7.1 Docker

• 职责：把应用、运行时和系统依赖封装成可版本化镜像。
• 适用：需要一致构建、隔离运行和标准部署入口的服务。
• 不解决：密钥、持久数据、资源配额和编排仍需平台能力。
• 验收：从干净环境构建，使用非 root 用户，检查健康、停止和镜像漏洞。

7.2 Kubernetes

• 职责：编排容器的部署、服务发现、扩缩容和故障恢复。
• 适用：服务数量、流量和组织能力确实需要集群调度的场景。
• 不解决：错误探针和资源限制会放大故障，集群不是应用正确性的替代品。
• 验收：区分 startup、readiness、liveness，测试滚动发布和节点中断。

7.3 MinIO

• 职责：提供兼容对象存储接口的文件与证据资产存储。
• 适用：保存原文、图片、评测数据和模型生成制品。
• 不解决：对象权限、版本、生命周期和元数据索引需要业务定义。
• 验收：测试上传校验、签名 URL、租户隔离、版本和灾备恢复。

八、组合选型顺序

1. 先用原生 SDK 和最小 API 跑通请求、错误与流式链路。
2. 确认确有多组件编排需求后再引入 LangChain 或其他应用框架。
3. 需要暂停、恢复和人工审批时，再评估 LangGraph 等状态图工具。
4. RAG 先建立带标注的查询集，再根据召回、过滤和规模选择存储。
5. 有明确多模型路由需求后再增加统一网关，保留直连对照测试。
6. 所有新组件都要有数据出口、版本固定、观测字段和替换方案。

九、总结

• 先按责任选工具：Web、编排、检索、任务、观测和部署解决的是不同问题。
• 先证明需求再加抽象：最小原生实现能暴露真实契约，也提供框架接入后的对照基线。
• 选型必须包含退出路径：数据格式、协议、配置和评测集应尽量保持可迁移。
• 验收要覆盖失败：超时、重复、权限、恢复和版本升级比一次成功调用更能说明生产可用性。