参考资料

• Diataxis documentation framework
• Google Technical Writing Courses

生产工程（17） - 附录：学习资料链接

这份索引只收录能够支持工程决策的一手资料。 阅读前先确认项目实际版本，再打开对应版本文档；搜索摘要和二手教程不能证明当前 API 契约。 每条资料都写明要解决的问题、应读取的部分和读完后的验证动作，避免“收藏即学会”。

一、模型 API 与 SDK

1.1 OpenAI API Reference

• 链接：OpenAI API Reference
• 解决问题：确认请求字段、响应对象、错误和分页等接口契约。
• 阅读重点：只读项目实际使用的端点，并核对 SDK 与 HTTP 字段映射。
• 验证动作：保存一次脱敏请求、原始响应、错误样本和模型标识。

1.2 Anthropic API Reference

• 链接：Anthropic API Reference
• 解决问题：确认 Messages API、认证、版本头和错误响应。
• 阅读重点：消息角色、内容块、工具使用、流式事件和限流信息。
• 验证动作：用最小请求覆盖普通响应、流式响应和一个无效参数。

1.3 Hugging Face Transformers

• 链接：Transformers documentation
• 解决问题：了解本地模型加载、Tokenizer、Pipeline 和生成参数。
• 阅读重点：目标模型类、设备与精度、生成配置和版本迁移说明。
• 验证动作：固定模型 revision，记录输入 Token、输出和资源占用。

二、应用框架与编排

2.1 LangChain

• 链接：LangChain documentation
• 解决问题：确认 Runnable、模型、Retriever、Tool 和流式组合方式。
• 阅读重点：输入输出类型、批处理、错误传播和目标版本的迁移说明。
• 验证动作：为 chain 的每一段打印可序列化中间结果并注入一次失败。

2.2 LangGraph

• 链接：LangGraph documentation
• 解决问题：设计有状态、多节点、可暂停和恢复的 Agent 工作流。
• 阅读重点：State、node、edge、checkpoint、interrupt 和持久化。
• 验证动作：覆盖正常分支、循环上限、中断恢复和重复副作用。

2.3 LlamaIndex

• 链接：LlamaIndex documentation
• 解决问题：连接数据源、构建索引和组合检索查询流程。
• 阅读重点：Reader、Node、Index、Retriever、metadata 和评测接口。
• 验证动作：把每个召回节点回链到原文页码或稳定文档位置。

2.4 Model Context Protocol

• 链接：MCP specification
• 解决问题：确认 MCP 客户端与服务端如何发现和调用工具、资源与 Prompt。
• 阅读重点：生命周期、能力协商、消息 Schema、错误和安全考虑。
• 验证动作：记录初始化协商、能力清单、一次非法调用和授权拒绝。

三、Python Web 与数据契约

3.1 Python

• 链接：Python documentation
• 解决问题：确认语言语义、标准库、虚拟环境和异步运行时行为。
• 阅读重点：项目实际 Python 小版本对应的文档与变更记录。
• 验证动作：在虚拟环境输出解释器路径和版本，再运行最小样本。

3.2 FastAPI

• 链接：FastAPI documentation
• 解决问题：构建带请求校验、依赖注入和 OpenAPI 的 Python API。
• 阅读重点：请求模型、错误处理、依赖、流式响应和部署。
• 验证动作：覆盖合法请求、422、权限拒绝、服务异常和客户端取消。

3.3 Pydantic

• 链接：Pydantic documentation
• 解决问题：确认数据模型、校验器、序列化和配置行为。
• 阅读重点：目标主版本的迁移说明，避免混用旧版写法。
• 验证动作：为缺字段、额外字段、类型转换和边界值写测试。

3.4 HTTPX

• 链接：HTTPX documentation
• 解决问题：配置同步或异步 HTTP 调用、连接池、超时和流式响应。
• 阅读重点：四类超时、客户端生命周期、异常类型和资源关闭。
• 验证动作：模拟连接失败、读取超时、4xx、5xx 和中途断流。

四、检索与存储

4.1 PostgreSQL

• 链接：PostgreSQL documentation
• 解决问题：确认事务、索引、锁、查询计划和备份恢复语义。
• 阅读重点：项目实际主版本，尤其是并发和 SQL 行为差异。
• 验证动作：保存 EXPLAIN、事务前后状态和并发冲突样本。

4.2 pgvector

• 链接：pgvector repository
• 解决问题：在 PostgreSQL 中选择向量类型、距离函数和索引。
• 阅读重点：维度、精度、HNSW/IVFFlat 参数、过滤与查询计划。
• 验证动作：用标注集比较召回、延迟、索引大小和更新成本。

4.3 Elasticsearch

• 链接：Elasticsearch reference
• 解决问题：设计字段映射、全文检索、过滤和向量检索。
• 阅读重点：目标集群版本的 mapping、analyzer、query DSL 和 kNN。
• 验证动作：保存查询 DSL、explain、候选分数、融合结果和耗时。

4.4 Milvus

• 链接：Milvus documentation
• 解决问题：评估大规模向量写入、索引、查询和集群能力。
• 阅读重点：Schema、索引、分区、过滤、一致性和备份。
• 验证动作：压测真实向量规模，并执行节点故障与恢复演练。

4.5 Neo4j Cypher

• 链接：Neo4j Cypher manual
• 解决问题：表达实体关系查询和多跳路径约束。
• 阅读重点：MATCH、路径、索引、查询计划和权限。
• 验证动作：把每条关系回链到来源，并测试缺边与错误实体消歧。

五、队列、缓存与任务

5.1 Redis

• 链接：Redis documentation
• 解决问题：确认数据结构、过期、持久化、集群和客户端行为。
• 阅读重点：TTL、淘汰策略、事务或 Lua、复制和故障切换。
• 验证动作：测试缓存穿透、并发更新、过期、重启和降级。

5.2 Celery

• 链接：Celery documentation
• 解决问题：配置 Python 异步任务、重试、路由和 worker。
• 阅读重点：确认投递语义、ack、超时、重试和结果后端。
• 验证动作：杀死执行中的 worker，检查任务是否重复及副作用是否幂等。

5.3 Apache Kafka

• 链接：Kafka documentation
• 解决问题：理解分区、消费者组、位点、保留和事务语义。
• 阅读重点：生产者确认、重复、顺序、再均衡和 Schema 演进。
• 验证动作：重放重复消息、消费者崩溃和积压恢复场景。

六、评测与可观测性

6.1 OpenTelemetry

• 链接：OpenTelemetry documentation
• 解决问题：统一采集 Trace、Metric、Log 并传播请求上下文。
• 阅读重点：Context propagation、span status、sampling 和语义约定。
• 验证动作：从浏览器请求追到模型、检索、数据库和工具调用。

6.2 Langfuse

• 链接：Langfuse documentation
• 解决问题：记录 LLM Trace、Prompt 版本、成本、反馈和评测。
• 阅读重点：数据模型、SDK、采样、数据集、权限和保留策略。
• 验证动作：检查父子 span、版本标签、脱敏和失败请求是否完整。

6.3 Ragas

• 链接：Ragas documentation
• 解决问题：构建 RAG 评测数据和使用可组合指标。
• 阅读重点：指标输入、评审模型、数据集格式和自定义 Rubric。
• 验证动作：保存逐样本结果，并与人工标注的一致性做抽样比较。

6.4 pytest

• 链接：pytest documentation
• 解决问题：组织 Python 单元、集成、参数化和 fixture 测试。
• 阅读重点：fixture 作用域、参数化、临时目录、失败输出和插件边界。
• 验证动作：固定随机种子和外部数据版本，重放一个异常路径。

6.5 Playwright

• 链接：Playwright documentation
• 解决问题：在真实浏览器中验收流式回答、错误和用户工作流。
• 阅读重点：Locator、自动等待、网络模拟、Trace 和多视口。
• 验证动作：覆盖桌面与移动端的慢响应、断流、取消和重试。

七、安全

7.1 OWASP LLM Top 10

• 链接：OWASP Top 10 for LLM Applications
• 解决问题：建立 Prompt Injection、敏感信息、供应链和过度代理等威胁清单。
• 阅读重点：每类风险的攻击前提、影响和缓解边界。
• 验证动作：把适用风险转成具体攻击样本、控制措施和责任人。

7.2 OWASP API Security

• 链接：OWASP API Security Top 10
• 解决问题：检查对象级授权、认证、资源消耗和服务端请求伪造。
• 阅读重点：把普通 API 风险与 LLM 特有风险共同建模。
• 验证动作：为跨租户 ID、批量接口、限流和 URL 参数写安全测试。

7.3 NIST AI Risk Management Framework

• 链接：NIST AI RMF
• 解决问题：从治理、识别、测量和管理角度组织 AI 风险工作。
• 阅读重点：根据系统影响范围选择控制，不把框架当作勾选清单。
• 验证动作：为高影响用例记录负责人、证据、剩余风险和复查周期。

八、容器与部署

8.1 Docker

• 链接：Docker documentation
• 解决问题：构建、运行和分发可复现的容器镜像。
• 阅读重点：多阶段构建、非 root、缓存、健康检查和 Compose。
• 验证动作：从干净环境构建并测试启动、健康、停止和只读配置。

8.2 Kubernetes

• 链接：Kubernetes documentation
• 解决问题：编排容器部署、服务、配置、扩缩容和恢复。
• 阅读重点：Deployment、Service、Config、Secret 和三类 Probe。
• 验证动作：模拟慢启动、依赖未就绪、Pod 中断和滚动回滚。

8.3 Prometheus

• 链接：Prometheus documentation
• 解决问题：采集时序指标并编写查询和告警规则。
• 阅读重点：指标类型、标签基数、PromQL、recording rule 和 alert。
• 验证动作：用人工故障触发告警，检查阈值、持续时间和恢复通知。

九、如何筛选新资料

9.1 必须回答的问题

1. 资料对应哪个具体版本、提交或协议版本？
2. 示例是否给出运行时、依赖、配置、输入和预期输出？
3. 是否解释适用条件、失败表现和替代方案？
4. 是否来自维护者、标准组织或官方产品文档？
5. 能否转成当前项目中的测试、指标或设计决策？

9.2 不进入长期索引的资料

• 只有截图，没有代码、配置或可复核输出。
• 只展示一次成功调用，没有异常路径和版本信息。
• 标题承诺生产方案，正文却只覆盖快速开始。
• 依赖已弃用 API，却没有迁移说明。
• 无法区分作者推断、产品事实和测量结果。

十、阅读记录模板

字段	要记录什么
工程问题	当前要做出的具体决策
版本范围	文档、库、模型或协议版本
关键契约	输入、输出、错误和状态变化
适用边界	数据、容量、权限和部署前提
失败样本	能推翻错误理解的最小反例
验证动作	命令、测试、Trace 或指标
项目结论	采用、拒绝、试验或待确认
复查条件	升级、规模变化或事故后重读

十一、总结

• 优先一手资料：官方文档和规范用于确认当前契约，二手内容只用于发现关键词。
• 先锁版本：同名 API 在不同版本可能有破坏性差异，示例可读不代表当前可运行。
• 阅读必须落地：每条资料至少转成一个接口断言、失败样本或选型结论。
• 资料不能替代验证：快速开始证明主路径，生产采用还要覆盖权限、限流、恢复和观测。
• 持续维护索引：依赖升级、协议变化或事故复盘后更新链接和阅读结论。