1. 项目概述从ADR到智能决策的工程化实践最近在整理过往项目文档时我重新审视了一个名为“ADR”的文件夹。这个文件夹隶属于一个更大的项目“sirius-777-llm”乍一看这个命名充满了神秘感像是某个科幻项目的一部分。实际上它指向了一个在现代软件工程尤其是涉及大型语言模型LLM的复杂系统中至关重要但常被忽视的环节架构决策记录Architecture Decision Record ADR。如果你正在或即将参与一个技术栈复杂、迭代快速、团队协作紧密的项目尤其是在AI应用开发领域那么理解并实践ADR很可能会成为你项目成功与否的分水岭。简单来说ADR不是一份事无巨细的设计文档也不是一份会议纪要。它是一份轻量级、版本化、面向未来的决策日志。它的核心价值在于当项目进行到第N个月有新成员加入或者老成员回头审视某个令人费解的技术选型时能够通过查阅ADR迅速理解“当初我们为什么选择了A方案而不是看起来更优的B方案”。在“sirius-777-llm”这类项目中技术决策点密集且关键例如为什么选择特定的LLM API供应商为什么设计这样的提示词工程流水线为什么采用某种特定的向量数据库分片策略这些决策背后往往有复杂的权衡ADR就是记录这些权衡过程的“黑匣子”。这个项目或这个文件夹的存在本身就暗示了一个成熟的工程实践将决策过程显式化、文档化并将其作为核心资产进行管理。它解决的痛点非常明确——避免“决策失忆”确保团队认知对齐并为未来的架构演进提供可靠的历史上下文。接下来我将结合自身在多个AI项目中的实战经验深入拆解如何构建一个真正有用、而非流于形式的ADR体系。2. ADR的核心价值与在LLM项目中的特殊意义2.1 为什么传统文档在LLM项目中“失灵”在常规的软件开发中我们习惯撰写详尽的技术设计文档Technical Design Document, TDD。这类文档通常追求全面、静态和最终性。然而在“sirius-777-llm”这类快速演进的LLM应用项目中这种模式面临巨大挑战。首先技术生态迭代极快。新的模型、框架、优化工具几乎每周都在涌现。上个月的最优解这个月可能就有了更高效的替代品。一份试图涵盖所有细节的静态设计文档很可能在写完之时就已部分过时。其次需求与能力的探索性极强。很多LLM应用的功能边界是在试错中明确的最初的架构假设可能会被实际验证推翻。最后决策的权衡因素更加多维。除了性能、成本、可维护性这些传统维度我们还需要考虑模型输出稳定性幻觉率、提示词维护成本、上下文窗口限制、微调数据准备难度等全新维度。ADR恰恰是针对这种动态、不确定环境而生的利器。它不追求描绘一个完美的终态而是忠实记录在某个特定时间点基于当时已知的信息和约束团队是如何做出选择的。每一份ADR都是一个决策的“快照”。2.2 ADR为LLM项目带来的四大核心收益基于在多个AI项目中的实践我总结出实施ADR能带来的最直接的四大收益构建团队集体记忆与上下文这是最根本的价值。LLM项目的技术栈通常很新很多决策依赖于前期的小规模实验POC结果。例如为什么选择ChatGPT的API而非Claude可能不是因为前者绝对更好而是因为在POC阶段前者在特定任务上的输出格式更稳定方便后续解析。这个细节如果不记录三个月后新来的工程师可能会提议切换团队需要重新花费时间解释甚至重新验证造成资源浪费。促进理性、结构化的决策过程ADR的模板强制要求填写“考虑的方案”、“决策结果”、“决策依据”等字段。这无形中要求决策者在会议或思考时必须系统地罗列选项、对比优劣而不是凭直觉或“我觉得”来做决定。例如在选择向量数据库时ADR会要求你列出对比Milvus、Pinecone、Weaviate的详细维度部署复杂度、云服务成本、社区支持、与现有系统的集成度等从而使决策更加客观。为新成员提供高效入职路径一份组织良好的ADR目录是新成员理解系统架构精髓的最佳教材。他们可以按时间顺序阅读像看故事一样了解系统是如何一步步演化到今天这个样子的理解每一个“奇怪”设计背后的历史原因这比阅读一份庞大的、已经失去上下文的静态架构图要有效得多。为架构重构和审计提供依据当业务发展需要重构系统时ADR是宝贵的审计线索。我们可以回顾当初决策所依赖的条件如“当时模型X的上下文窗口只有4K”是否已经改变现在模型Y支持128K。如果核心约束条件已不复存在那么推翻旧决策、进行架构演进就具备了充分理由。注意切忌把ADR写成“事后找补”的合理化说明。它的灵魂在于记录决策时的真实思考过程包括那些被放弃的、看似有吸引力的选项。记录下“我们曾考虑过方案B它简单且成本低但因为无法满足未来6个月预计增长10倍的并发要求而放弃”远比只歌颂已选方案A的优点更有价值。3. 如何设计一份务实可用的ADR文档模板一个糟糕的模板会让ADR写作变成负担一个好模板则能引导思考。经过多个项目的迭代我目前使用的ADR模板包含以下核心部分它平衡了完备性和写作成本# [ADR-001] 为LLM服务层选择gRPC作为主要通信协议 ## 状态 提议 | 已接受 | 已弃用 | 已取代 **当前状态** 已接受 (2023-10-26) ## 决策背景 我们正在构建“sirius-777-llm”项目的核心推理服务。该服务需要被多个上游业务模块如Web后端、数据流水线、内部工具以低延迟、高并发的形式调用。当前使用HTTP/JSON的临时方案在压测下出现了性能瓶颈和序列化开销问题。 ## 考虑的方案 1. **方案A继续使用HTTP/JSON RESTful API** * **优点**实现简单通用性强易于调试可直接用curl或Postman。 * **缺点**序列化/反序列化开销大头部冗长缺乏强类型约束双向流支持复杂。 2. **方案B采用gRPC框架** * **优点**基于HTTP/2多路复用降低延迟使用Protocol Buffers二进制序列化效率极高自动生成强类型客户端/服务端代码减少错误原生支持双向流为未来实时交互功能预留空间。 * **缺点**需要定义.proto文件学习曲线稍陡浏览器直接调用需要grpc-web网关调试不如HTTP直观。 3. **方案C使用GraphQL** * **优点**客户端可精确查询所需数据避免过度获取单一端点。 * **缺点**对于以“请求-响应”模式为主的LLM推理场景优势不明显服务端实现复杂度高缓存机制更复杂。 ## 决策结果 我们决定采用 **方案BgRPC框架**。 ## 决策依据 1. **性能是核心关切**压测数据显示在相同负载下gRPC相比HTTP/JSON的延迟降低约60%吞吐量提升约3倍。这对于LLM推理这种计算密集型服务的响应时间至关重要。 2. **强类型保障系统健壮性**LLM服务的输入输出结构复杂可能包含多轮对话历史、系统指令、工具调用规范等。.proto文件可以作为唯一的、版本化的接口契约防止前后端数据结构不一致导致的运行时错误。 3. **面向未来扩展**原生双向流支持为后续实现“流式Token输出”、“服务端推送中断信号”等高级特性提供了基础设施无需重构通信层。 4. **团队能力可覆盖**团队中有成员具备gRPC经验且主流编程语言都有成熟支持学习成本可控。对于浏览器调用需求可通过轻量的grpc-web网关解决影响面有限。 ## 影响与后果 ### 正面影响 * 服务间调用性能显著提升。 * 接口定义更加清晰和稳定。 * 为实现流式输出打下了基础。 ### 负面影响 * 前端同学需要适应通过grpc-web网关进行调用调试流程需要调整。 * 需要引入新的工具链protoc编译器、相关插件并整合到CI/CD中。 ## 相关决策链接 * [ADR-000]项目初始技术栈选型 * [PROTO-001]LLM推理服务核心接口定义模板使用心得标题编号使用ADR-001这样的序列号便于索引和引用。状态跟踪“状态”字段至关重要。决策可能被后续的新ADR推翻状态变为“已取代”明确状态可以避免团队参考过时的决策。背景清晰用简练语言说明“当时遇到了什么问题”这是理解后续所有内容的基石。方案对比表格化在“考虑的方案”部分我习惯用列表清晰罗列关键优缺点一目了然。避免大段散文式描述。依据量化优先在“决策依据”中尽可能使用数据如压测结果、成本估算说话。其次是可推导的逻辑如“为未来特性预留空间”。最次是主观判断如“团队更熟悉”但即便如此也要写明是哪些成员熟悉熟悉到什么程度。不回避负面影响诚实地记录“负面影响”这既是风险管理也为后续可能出现的“为什么我们当初要选这个麻烦东西”的质疑提供了预先答复。4. ADR在LLM项目中的典型应用场景与实操记录在“sirius-777-llm”这类项目中哪些决策值得被记录成ADR以下是我从实际项目中提炼出的几个高价值场景及其实操要点。4.1 场景一核心模型API供应商选型这是LLM项目的基石级决策。记录此ADR时重点不在于罗列所有供应商而在于阐明评估框架和关键决胜因素。实操记录我们当时面临的选择包括OpenAI GPT-4、Anthropic Claude、以及国内的一些大模型API。在ADR中我们首先明确了评估维度能力维度在特定任务如长文本总结、代码生成、逻辑推理上的基准测试分数。成本维度按我们的预估调用量月度成本测算。稳定性与运维维度API的SLA承诺、历史故障率、监控工具生态。合规与数据安全维度数据出境政策、供应商的数据处理协议。生态与工具链SDK成熟度、是否有针对性的优化工具如LangChain集成深度。决策过程关键点我们并没有单纯选择“能力最强”或“最便宜”的模型。我们设计了一个加权评分卡。例如对于我们的核心场景客服对话摘要能力权重占40%成本占30%稳定性占20%其他占10%。然后为每个候选者在每个维度上打分。最终模型A虽然在绝对能力上得分第二但其极高的成本拉低了总分模型B能力第一且成本适中但在稳定性历史上得分较低模型C能力稍逊但仍超过基线但成本最优且稳定性满分。经过激烈讨论我们选择了模型C。ADR记录的核心在ADR的“决策依据”中我们详细记录了这张评分卡、权重设定的理由为什么客服场景下稳定性权重高达20%因为服务中断直接影响客户体验以及最终选择模型C的决定性因素在满足能力基线的前提下其卓越的性价比和稳定性承诺为我们项目初期的快速迭代和成本控制提供了坚实保障。同时我们也记录了“我们计划每季度重新评估此决策”为未来切换供应商埋下伏笔。4.2 场景二提示词Prompt工程与管理策略提示词是LLM应用的“源代码”。如何管理这些不断迭代、版本繁多的提示词是一个必须通过ADR明确的重要工程决策。实操记录我们考虑了三种方案方案A硬编码在业务代码中。简单但任何修改都需要重新部署服务难以进行A/B测试且容易在代码中散落得到处都是。方案B存储在关系型数据库如PostgreSQL中。便于动态更新和版本管理但缺乏对结构化内容如few-shot示例的良好查询支持。方案C使用专门的配置中心或文档数据库如MongoDB并建立Git仓库同步机制。将提示词视为独立的配置文件存储在Git中实现版本控制通过配置中心下发到应用数据库仅作缓存和元数据管理。决策与实施细节我们选择了方案C并设计了具体的工作流每个提示词模板是一个YAML文件包含id、描述、系统指令、用户指令模板、few_shot_examples、版本、创建者等字段。这些YAML文件存放在一个独立的Git仓库中通过Pull Request进行变更评审CI会自动进行基础的语法检查和模板变量验证。服务启动时从配置中心拉取最新版本的提示词配置并缓存。配置中心后端与Git仓库同步。在数据库中我们只存储prompt_id和version以及每次调用的日志用于后续分析和提示词优化。ADR记录的价值这份ADR不仅记录了选择方案C更重要的是记录了这个工作流的设计细节和选型理由。例如为什么选择YAML而不是JSON因为YAML支持多行字符串更适合编写长篇提示词。为什么引入Git PR流程因为提示词的调整需要算法工程师、产品经理和业务方共同评审Git的协作流程最成熟。这份ADR成为了后续所有提示词开发者的操作手册避免了每个人用不同的方式管理提示词导致的混乱。4.3 场景三向量数据库的选型与部署模式当项目涉及RAG检索增强生成时向量数据库的选型至关重要。这个决策涉及技术、运维和成本的多重考量。实操记录我们对比了Pinecone全托管、Weaviate自托管/托管均可、Qdrant自托管和PGVectorPostgreSQL扩展。在ADR中我们创建了一个详细的对比表格维度PineconeWeaviate (自托管)Qdrant (自托管)PGVector部署复杂度极低SaaS中K8s Helm Chart低单一二进制低已有PG运维负担无高需监控、备份、升级中低与PG一同运维初期成本高有最低消费低仅服务器成本低极低扩展性自动弹性伸缩手动分片复杂度高支持集群需手动配置依赖PG扩展能力功能特性核心向量检索支持混合搜索、GraphQL过滤条件性能好与SQL生态无缝集成团队熟悉度新新新高决策的深层逻辑经过讨论我们排除了PGVector因为预计的向量数据量和查询QPS较高担心对现有业务数据库造成冲击。在Pinecone和自托管方案之间我们产生了分歧。支持Pinecone的理由是“让专业的人做专业的事”团队可以聚焦业务逻辑。支持自托管最终选了Qdrant的理由则基于两点1)成本控制长期来看自托管的服务器成本远低于SaaS服务费且我们的数据量增长可预测2)数据主权与网络延迟所有数据留在自有环境且服务间内网调用延迟极低、更稳定。ADR如何记录权衡在“决策依据”部分我们没有简单地写“选择了Qdrant”。我们写道“在项目初期快速启动和降低运维负担是优先项Pinecone是更优选择。但基于本项目的长期规划3年、对数据隐私的较高要求、以及团队具备容器化运维能力我们决定承担初期更高的搭建成本以换取长期的技术自主权和更低的TCO总拥有成本。选择Qdrant而非Weaviate是因为其架构更简洁文档清晰且基准测试中在过滤查询场景下性能表现更符合我们的业务查询模式。” 这样的记录即使未来有人质疑“当初为什么不用更省事的Pinecone”也能一目了然。5. ADR工作流的建立与团队文化培育有了好的模板和场景如何让ADR真正融入团队的工作流而不是沦为“额外的文档负担”这是成败的关键。5.1 将ADR嵌入开发流程我们的实践是将ADR的创建和评审作为技术设计方案评审Tech Design Review的强制性产出物。触发时机当一项技术决策满足以下任一条件时必须发起ADR流程影响系统核心架构如通信协议、数据存储方案。引入新的重大技术依赖如新的数据库、中间件、第三方服务。涉及显著的跨团队协作或长期维护成本。存在多个可行方案且各有优劣需要正式记录选择理由。流程闭环提案决策发起人根据模板起草ADR状态标记为“提议”。讨论与评审在技术评审会议上围绕ADR文档展开讨论。重点审查“考虑的方案”是否全面“决策依据”是否充分。记录与归档会议达成一致后更新ADR状态为“已接受”并合并到项目代码仓库的docs/adr/目录下与代码版本一同管理。通知将已接受的ADR链接同步到相关项目的README或架构概览文档中。5.2 工具链支持版本控制ADR必须放在Git仓库中如docs/adr/。这样它们就有了历史版本可以追溯修改并且与相关的代码变更通过Commit关联起来。目录与索引在docs/adr/目录下维护一个README.md或index.md文件以表格形式列出所有ADR包含编号、标题、状态、日期和简短摘要。这相当于决策日志的目录。| 编号 | 标题 | 状态 | 日期 | 摘要 | |------|------|------|------|------| | 0001 | 选择gRPC作为主要通信协议 | 已接受 | 2023-10-26 | 为提升性能与强类型约束... | | 0002 | LLM API供应商选型 | 已接受 | 2023-11-05 | 基于多维度评估选择模型C... | | 0003 | 提示词管理策略 | 已接受 | 2023-11-20 | 采用Git配置中心管理提示词... |轻量级工具对于小型团队Markdown文件加Git就足够了。如果追求更自动化可以考虑使用像adr-tools这样的命令行工具来生成模板和管理状态。5.3 培育“决策透明”的团队文化这是最难但最重要的一环。管理者和技术负责人需要以身作则自上而下推行在项目启动初期由架构师或技术负责人撰写最初几份关键的ADR作为范本。强调价值而非负担在团队内部分享因缺乏ADR而导致的“历史之谜”和沟通成本让大家切身感受到其价值。例如“还记得我们上周花了半天时间争论为什么不用Redis而用Memcached吗如果当时有ADR5分钟就能搞清楚。”鼓励挑战与更新明确ADR不是“圣旨”。当有新的事实、技术或需求出现时鼓励团队成员提出新的ADR来挑战或取代旧的决策。将状态更新为“已取代”不是失败而是架构健康演进的标志。在入职流程中引入要求新成员在熟悉代码前先阅读核心的ADR索引让他们快速理解系统的设计脉络。6. 常见陷阱、问题排查与进阶技巧即使理解了ADR的价值和流程在实际操作中仍会踩坑。以下是一些常见问题及应对策略。6.1 常见陷阱ADR过于冗长或过于简略问题要么像写论文事无巨细要么只有一句话结论。排查检查是否遵循了模板。核心应聚焦在“背景”、“方案对比”、“决策依据”和“影响”。技术细节可以链接到详细设计文档。技巧假设读者是一个一年后的新同事。他需要多少信息才能理解这个决策以此为尺度来把握详略。把ADR写成“事后诸葛亮”或“邀功报告”问题只记录最终成功的方案和它的优点对当初的犹豫、被否定的优秀方案闭口不谈。排查检查“考虑的方案”部分是否真诚地列出了其他选项及其真实优点。“决策依据”是否承认了已选方案的缺点技巧在评审时可以特意问“我们当时有没有考虑过XX方案为什么没选它” 把讨论过程记录下来。有始无终状态永不更新问题ADR写完就扔进文件夹决策被推翻了也没人更新状态。排查建立定期如每季度回顾ADR的机制。在涉及重大架构变更的代码评审中要求关联的ADR必须被提及和评估。技巧在团队看板或Wiki首页设置一个“待回顾ADR”列表提醒大家哪些决策可能因条件变化而需要重新审视。与代码和现实脱节问题ADR记录的选择是A但实际代码中实现的是B或者参数已经完全不同。排查在代码的关键部分如配置定义、初始化模块添加注释引用相关的ADR编号。例如// 使用gRPC通信详见 ADR-001。技巧将ADR检查纳入发布流程或关键合并请求Merge Request的检查项中确保重大变更都有文档依据。6.2 进阶技巧让ADR发挥更大价值决策日志与项目周报/月报结合在项目定期同步中不仅同步完成了什么功能也同步做出了什么重要技术决策附上ADR链接。这能让所有干系人包括非技术成员理解技术演进的脉络。建立ADR间的关联网络一份ADR可能会引用或影响另一份。在ADR中通过“相关决策链接”字段建立这种关联。例如一份关于“引入缓存”的ADR可能会链接到之前关于“数据库选型”和“API设计”的ADR。这有助于构建一个立体的决策知识图谱。用于风险评估和预案制定在记录“负面影响”时其实就是在进行风险识别。团队可以基于此提前制定缓解预案。例如选择了自托管向量数据库负面影响是“运维负担高”那么预案可以是“编写详细的运维手册并安排专人负责头三个月的监控和调优”。作为技术债的“借条”有时我们不得不为了赶工期而做出一个次优的短期决策例如先使用简单的文件存储而不是上数据库。在ADR中诚实记录这是一个“临时方案”并明确记录“技术债条目需要在Q3前重构为数据库存储详见未来ADR”。这使技术债显性化、可追踪。回顾“sirius-777-llm/ADR”这个项目它代表的不仅仅是一个存放文档的文件夹更是一种面向复杂性和不确定性的工程哲学。在技术日新月异、需求快速变化的今天尤其是AI原生应用开发领域我们无法依靠一份完美的前期设计图走到终点。我们需要的是一套机制能够持续地、结构化地记录我们如何在每一个岔路口做出选择以及为什么这么选。这套机制就是ADR。它让团队的智慧得以沉淀让系统的演进有迹可循最终让“sirius-777-llm”这样的复杂项目从一个充满未知的探索变成一场步步为营的扎实建设。开始为你的下一个重要决策写一份ADR吧这是你送给未来自己和团队的一份宝贵礼物。