1. 项目概述当AI全栈开发遇上现代工程体系最近在得物技术团队内部我们完成了一次将AI应用开发与现代化软件交付工程体系深度融合的实践。这个项目的核心是将Harness、SDDSoftware Design Document软件设计文档驱动以及多仓管理模式这三个看似独立的工程实践整合进一个典型的AI全栈开发流程中。听起来有点复杂简单来说我们想解决的痛点是当团队从传统的Web或移动端开发转向构建包含大模型、智能体Agent的复杂AI应用时原有的开发、协作和交付流程开始“水土不服”效率和质量都面临挑战。传统的AI项目尤其是涉及大模型微调或智能体编排的常常陷入“数据科学家写Jupyter Notebook工程师再艰难复现和部署”的困境。而现代软件工程强调的自动化、文档化和模块化在AI领域往往被忽视。我们这次实践的目标就是要把软件工程里那些被验证过的好方法系统地引入AI全栈开发让AI应用的构建像构建一个微服务一样清晰、可控和高效。这不仅仅是工具链的堆砌更是一种开发范式的转变。2. 核心理念与架构选型解析2.1 为什么是Harness SDD 多仓管理在启动项目前我们评估了多种方案。最终选定这个组合是基于以下几个核心考量Harness自动化与可观测性的基石Harness的核心价值在于它将CI/CD、功能开关、混沌工程等能力平台化。对于AI应用尤其是涉及模型迭代和A/B测试的场景自动化流水线至关重要。想象一下每次数据科学家更新了一个模型权重文件都需要手动打包、部署、配置环境出错率高且耗时。Harness可以让我们定义一条从代码提交、模型训练或下载、到容器化部署的全自动化流水线。更重要的是它的可观测性面板能集成模型推理的延迟、准确率等关键指标让“模型性能”也成为可监控、可告警的运维对象。SDD驱动对抗AI项目的“黑盒”与“模糊”AI项目特别是基于大语言模型LLM的应用需求边界容易模糊。“让对话更智能”这种需求在开发过程中会不断衍生出新的细节。SDD驱动开发要求我们在写第一行代码前先撰写一份详细的软件设计文档。这份文档需要明确系统边界AI能力的具体范围是什么是仅做意图识别还是需要调用工具Tools工具列表是什么Prompt设计系统提示词System Prompt、用户消息处理流程、上下文管理策略。非功能性需求响应时间要求如P99延迟2秒、单次对话的Token成本上限、模型的热更新策略。评估方案如何衡量“更智能”是人工评测打分还是通过自动化测试集计算准确率通过强制性的SDD评审我们让产品、算法、工程、测试各方在项目早期就对“要建成什么样”达成精确共识极大减少了后期的返工和扯皮。多仓管理模式解耦复杂性与独立演进一个全栈AI应用可能包含多个组件前端界面、后端API服务、模型服务Model Serving、向量数据库、特定的数据处理流水线等。如果所有代码都放在一个巨型仓库Monorepo里任何微小的修改都会触发全量的CI/CD依赖管理也会变成噩梦。我们采用多仓管理每个核心组件或服务拥有独立的代码仓库。例如ai-agent-orchestrator负责智能体的流程编排与工具调用。model-service封装对各类大模型API如GPT、Claude或自研模型的调用。knowledge-rag-service处理文档切片、向量化存储与检索增强生成RAG逻辑。frontend-chat-interface用户交互界面。每个仓库有独立的生命周期、版本号和部署流程。通过清晰的接口契约如gRPC协议或REST API规范进行通信。这种模式使得团队可以并行开发技术栈选择也更灵活例如模型服务用Python编排服务用Go。2.2 整体架构视图与数据流基于上述理念我们设计的系统架构是一个清晰的松散耦合分层架构。前端层一个轻量级的Web应用使用React或Vue提供聊天界面并通过WebSocket或HTTP长轮询与后端网关通信。API网关层作为统一的入口点处理用户认证、限流、请求路由。它将用户请求分发到后端的业务编排服务。业务编排层AI Agent Orchestrator这是系统的“大脑”。它接收用户问题决定调用哪个工具如搜索知识库、查询数据库、执行代码管理多轮对话的上下文Context并最终将模型生成的结果格式化后返回。这里会大量运用SDD中定义的Prompt模板和流程逻辑。AI能力服务层这是一个服务集合。模型服务对接云端大模型API或部署本地模型。负责处理Token计算、费用控制、Fallback策略当主模型失败时自动切换备用模型。知识服务RAG管理企业私有知识库。用户提问时从此服务检索最相关的文档片段作为上下文注入给大模型实现精准回答。工具服务提供AI Agent可以调用的具体功能如天气查询、订单状态检索、代码执行沙箱等。每个工具都是一个独立的微服务。数据与基础设施层包括向量数据库如Milvus, Pinecone、关系型数据库、对象存储用于存放模型文件、文档源文件以及由Harness管理的Kubernetes集群所有服务都容器化部署于此。整个数据流是用户输入 - 网关 - 编排器 - 可选调用知识服务检索/调用工具服务执行- 模型服务生成 - 编排器格式化 - 网关 - 用户输出。Harness的流水线覆盖了从代码提交到每个服务容器镜像构建、安全扫描、部署到K8s的全过程。3. 核心实践SDD驱动下的AI需求拆解与设计3.1 如何撰写一份合格的AI项目SDDSDD不是一份空洞的概述而是一份可执行的技术蓝图。对于AI项目我们将其核心章节扩展为1. 业务目标与成功指标目标不是“提升智能客服水平”而是“在机票退改签场景下将AI客服的意图识别准确率从85%提升至95%并将首次解决率提升15%”。成功指标必须可量化。例如自动化测试集包含1000个标注好的用户问法上的意图识别F1-score线上真实对话的用户满意度评分CSAT平均值平均对话轮次越低越好代表效率高。2. 系统架构与组件设计绘制详细的架构图标明各服务边界和通信协议。重点描述AI核心组件Agent类型是单一任务Agent还是基于ReAct或Plan-and-Execute模式的复杂Agent上下文管理上下文窗口多大采用何种摘要或滑动窗口策略来节省Token工具设计每个工具的名称、功能描述、输入/输出JSON Schema、错误处理方式。Prompt工程给出核心Prompt模板包括系统角色设定、少样本示例Few-shot Examples、输出格式指令。3. 数据流与接口定义用序列图描述一次典型用户交互的完整流程。定义所有内部服务间API的详细规范可以使用OpenAPI Specification。4. 非功能性需求性能端到端响应时间P95 3秒。成本平均单次对话Token消耗不超过2000折算成本低于0.01元。可维护性Prompt模板必须版本化、外部化配置如存储在数据库或配置中心支持热更新无需重启服务。安全性用户输入输出过滤、Prompt注入攻击防护、工具调用的权限校验。5. 测试与评估策略单元测试对工具函数、Prompt渲染逻辑进行测试。集成测试模拟用户对话验证整个Agent流程。评估体系除了线上指标建立离线评估流水线定期用最新的测试集跑模型监控性能波动。注意SDD评审会是最关键的环节。必须要求算法工程师、后端工程师、前端工程师、测试工程师和产品经理全部参与。评审的重点是确认接口契约、评估方案的可行性和非功能性需求的合理性。3.2 从SDD到任务拆解与排期一份通过的SDD会直接转化为Jira或类似项目管理工具中的Epic和Story。每个Story对应SDD中的一个可交付模块例如“Story-101: 实现机票退改签意图识别Prompt模板V1.0并在测试集上达到90%准确率”。“Story-102: 开发‘查询订单状态’工具服务提供RESTful API并集成到Agent工具列表”。“Story-103: 搭建Harness流水线实现model-service的自动化构建与部署”。这样整个AI项目就从“探索性实验”转变为“有明确验收标准的工程项目”。4. 基于Harness的AI应用CI/CD流水线构建4.1 流水线设计不止于构建与部署对于AI应用CI/CD流水线需要处理更多特殊工件和步骤。我们为model-service仓库设计的Harness流水线包含以下阶段1. 代码拉取与质量门禁触发Git仓库的main或release/*分支有新的合并请求。步骤代码静态分析SonarQube、安全检查检查依赖漏洞如torch版本是否存在已知CVE。2. 模型资产处理这是AI流水线的特色步骤。如果SDD中定义使用特定微调模型或嵌入模型此步骤负责方案A下载从指定的模型仓库如Hugging Face、公司内部模型库下载指定版本的模型文件使用校验和验证完整性。方案B训练触发一个独立的、资源消耗更大的训练流水线可能运行在GPU集群上训练完成后将产出的模型权重文件归档到对象存储并生成版本元数据。将模型文件打包进Docker镜像的特定目录或准备作为Volume挂载的路径。3. 容器镜像构建与推送使用多阶段构建的Dockerfile以减小最终镜像体积。将上一步处理好的模型资产如果需要复制到镜像中。将镜像推送到私有镜像仓库如Harbor标签包含Git提交哈希和日期。4. 自动化测试单元测试运行Pythonpytest。集成测试部署一个临时测试环境Namespace启动该服务及其依赖如向量数据库模拟器运行集成测试套件验证模型调用和基础功能。5. 安全扫描与合规检查对生成的Docker镜像进行漏洞扫描使用Trivy或Clair。检查镜像中是否包含不合规的许可证或敏感信息。6. 部署到环境金丝雀发布首先将新版本部署到K8s集群中但只将少量如5%的线上流量路由到新版本Pod同时通过Harness集成的监控观察错误率、延迟等指标。渐进式交付如果金丝雀阶段指标正常逐步将流量比例提升至20%、50%、100%。在整个过程中可以随时通过Harness界面一键回滚。7. 后置步骤模型性能监控集成流水线最后一步会更新Harness或关联的可观测性平台如Datadog, Prometheus中的配置确保新部署的服务实例的指标如model_inference_latency_seconds,token_usage_per_request能被正确采集和告警。4.2 环境管理与配置分离我们利用Harness的环境管理和配置覆盖功能为dev、qa、staging、prod分别定义配置。开发环境可能使用较小的模型如text-embedding-3-small和模拟的工具服务以节省成本和加速测试。生产环境使用性能最强的模型如gpt-4-turbo并连接真实的工具和数据库。API密钥、模型端点等敏感信息通过Harness的加密Secret管理绝不硬编码在代码或镜像中。5. 多仓模式下的开发协作与依赖管理5.1 仓库划分原则与接口契约如何划分仓库是个技术活。我们的原则是“高内聚、低耦合”和“独立发布能力”。高内聚一个仓库内的代码应属于同一个明确的业务域或技术域。例如所有与“订单”相关的工具服务查询、创建、取消可以放在一个order-tools仓库。低耦合仓库之间只能通过明确定义的APIHTTP/gRPC或消息队列进行通信禁止直接数据库访问或共享内存等紧耦合方式。独立发布每个仓库应有自己的版本号遵循SemVer并且其修改和发布不应强制要求其他仓库同步更新。接口契约的管理我们使用Protobuf用于gRPC或OpenAPI Spec用于REST来严格定义服务间的接口。这些.proto或.yaml文件存放在一个独立的api-contracts仓库中。所有依赖该接口的服务都通过Git Submodule或包管理工具如将编译后的客户端代码发布到私有PyPI/NPM来引用特定版本的契约。这确保了前后端和不同服务之间的兼容性。5.2 开发工作流与版本协调在多仓模式下一个功能的开发可能涉及多个仓库的改动。我们采用以下工作流创建功能分支在相关的每个仓库如agent-orchestrator和order-tools中基于main分支创建同名功能分支如feature/refund-assistant。同步开发与测试开发者在各自分支上修改代码。本地通过Docker Compose启动一个包含所有依赖服务的完整环境进行集成测试。更新接口契约如果功能需要修改接口首先向api-contracts仓库提交Pull Request评审通过合并后生成新版本的客户端代码。依赖升级在各个服务仓库中更新对api-contracts新版本的依赖。分别发起PR向各个仓库的主分支发起合并请求。每个PR的CI流水线都会运行。协调发布所有PR合并后通过Harness流水线分别部署各个服务。为了功能一致性我们可能会使用功能开关Feature Flag。新功能代码部署后默认关闭待所有相关服务就绪后再通过Harness的功能开关管理界面统一开启。实操心得多仓管理初期会增加一些协调成本但长期来看它带来的模块清晰度、独立可扩展性和技术选代灵活性是巨大的优势。关键在于建立严格的接口契约文化和高效的本地集成测试环境。6. 典型场景实战构建一个智能客服订单查询助手让我们通过一个简化场景串联上述所有实践。目标是构建一个能理解用户自然语言、自动查询订单状态并回复的AI助手。Step 1: SDD撰写与评审我们首先撰写SDD明确工具只有一个get_order_status工具输入订单号返回订单状态、商品信息、物流信息。Prompt设计系统Prompt会定义助手角色并说明“当用户询问订单情况时你必须主动询问或提取订单号然后调用get_order_status工具。”输出要求模型将工具返回的JSON数据转化为一段友好、自然的回复文本。Step 2: 多仓开发在order-tools仓库开发get_order_status工具的gRPC服务。在api-contracts仓库定义该工具的.proto文件。在agent-orchestrator仓库集成api-contracts生成的客户端并在Agent的工具列表中注册该工具编写调用逻辑和结果处理逻辑。在frontend-chat-interface仓库开发聊天界面。Step 3: Harness流水线配置为order-tools和agent-orchestrator分别配置Harness流水线包含构建、测试、安全扫描、金丝雀部署等步骤。在agent-orchestrator的流水线中增加一个“Prompt模板验证”步骤从配置中心拉取最新的Prompt用一组预定义的测试用例如“我的订单12345到哪了”发起模拟请求验证Agent是否能正确调用工具并返回格式正确的回复。Step 4: 集成与发布所有服务通过流水线部署到测试环境。进行端到端集成测试。使用功能开关控制新助手功能。一切就绪后在Harness中打开开关功能灰度上线。7. 避坑指南与效能提升在实践中我们踩过不少坑也总结出一些提升效能的技巧。常见问题与排查Agent无限循环或调用错误工具现象Agent反复调用同一个工具或调用了不相关的工具。排查首先检查SDD中的Prompt设计是否对工具的选择条件描述不清。其次在日志中输出Agent每一步的“思考过程”Chain-of-Thought这是调试Agent行为的最重要依据。可以临时增加日志级别查看模型生成的中间文本。解决优化Prompt提供更清晰的工具描述和调用示例。为工具调用增加防护逻辑比如单轮对话中同一工具最多调用3次。流水线中模型下载超时或失败现象CI/CD流水线在下载数GB的大模型时网络超时。解决不要在每次流水线中都从公网下载。建议在公司内网搭建模型镜像仓库如使用Hugging Face的hf-transfer加速或自建镜像站。流水线从内网镜像站下载速度稳定且可控。多仓开发时本地环境搭建复杂现象开发者需要手动启动五六个服务才能开始调试。解决使用docker-compose.yml或Tilt工具定义完整的本地开发环境。一个命令即可拉起所有依赖服务使用测试版本或模拟器。确保这个配置文件在项目根目录或一个独立的dev-env仓库中维护。效能提升技巧Prompt模板管理不要将Prompt硬编码在代码中。使用数据库或配置中心如Consul, Apollo存储和管理Prompt模板。这样可以在不重启服务的情况下动态调整Prompt进行A/B测试或快速修复问题。Harness的部署功能可以很方便地触发配置更新。测试数据工厂建立丰富的测试用例库不仅包含正向用例更要包含各种边界和对抗性用例如用户输入乱码、故意进行Prompt注入攻击。将这些用例集成到Harness流水线的自动化测试阶段作为质量门禁。成本与性能监控看板在Harness或Grafana中建立专属看板监控每个AI服务的核心指标请求量、平均响应延迟、Token消耗分布、模型调用失败率、各工具调用次数等。设置告警当单次对话成本异常偏高或延迟陡增时能及时通知负责人。“Harness Agent”与“AI Agent”的区分这是一个容易混淆的概念。在我们这个上下文中Harness是一个软件交付平台它内部的“Delegate”可以看作其执行任务的代理一种软件代理。而AI Agent是指具有自主理解、规划和执行能力的人工智能体。二者完全不在一个层面。Harness平台可以用来部署、管理和监控运行AI Agent的服务但本身并不是AI Agent。这次将Harness、SDD和多仓管理融入AI全栈开发的实践让我们深刻体会到AI工程的成熟度直接决定了AI应用能否从“演示原型”走向“稳定生产”。这套组合拳打下来最直观的感受是“可控”。需求变更可控、代码质量可控、发布风险可控、线上表现可控。它或许不是唯一答案但为我们团队在快速变化的AI浪潮中提供了一条稳健前行的工程路径。如果你也在探索AI项目的工程化不妨从一份详尽的SDD和一个自动化的部署流水线开始这会是回报率最高的投入。 AI全栈开发工程化实践：Harness流水线、SDD驱动与多仓管理
1. 项目概述当AI全栈开发遇上现代工程体系最近在得物技术团队内部我们完成了一次将AI应用开发与现代化软件交付工程体系深度融合的实践。这个项目的核心是将Harness、SDDSoftware Design Document软件设计文档驱动以及多仓管理模式这三个看似独立的工程实践整合进一个典型的AI全栈开发流程中。听起来有点复杂简单来说我们想解决的痛点是当团队从传统的Web或移动端开发转向构建包含大模型、智能体Agent的复杂AI应用时原有的开发、协作和交付流程开始“水土不服”效率和质量都面临挑战。传统的AI项目尤其是涉及大模型微调或智能体编排的常常陷入“数据科学家写Jupyter Notebook工程师再艰难复现和部署”的困境。而现代软件工程强调的自动化、文档化和模块化在AI领域往往被忽视。我们这次实践的目标就是要把软件工程里那些被验证过的好方法系统地引入AI全栈开发让AI应用的构建像构建一个微服务一样清晰、可控和高效。这不仅仅是工具链的堆砌更是一种开发范式的转变。2. 核心理念与架构选型解析2.1 为什么是Harness SDD 多仓管理在启动项目前我们评估了多种方案。最终选定这个组合是基于以下几个核心考量Harness自动化与可观测性的基石Harness的核心价值在于它将CI/CD、功能开关、混沌工程等能力平台化。对于AI应用尤其是涉及模型迭代和A/B测试的场景自动化流水线至关重要。想象一下每次数据科学家更新了一个模型权重文件都需要手动打包、部署、配置环境出错率高且耗时。Harness可以让我们定义一条从代码提交、模型训练或下载、到容器化部署的全自动化流水线。更重要的是它的可观测性面板能集成模型推理的延迟、准确率等关键指标让“模型性能”也成为可监控、可告警的运维对象。SDD驱动对抗AI项目的“黑盒”与“模糊”AI项目特别是基于大语言模型LLM的应用需求边界容易模糊。“让对话更智能”这种需求在开发过程中会不断衍生出新的细节。SDD驱动开发要求我们在写第一行代码前先撰写一份详细的软件设计文档。这份文档需要明确系统边界AI能力的具体范围是什么是仅做意图识别还是需要调用工具Tools工具列表是什么Prompt设计系统提示词System Prompt、用户消息处理流程、上下文管理策略。非功能性需求响应时间要求如P99延迟2秒、单次对话的Token成本上限、模型的热更新策略。评估方案如何衡量“更智能”是人工评测打分还是通过自动化测试集计算准确率通过强制性的SDD评审我们让产品、算法、工程、测试各方在项目早期就对“要建成什么样”达成精确共识极大减少了后期的返工和扯皮。多仓管理模式解耦复杂性与独立演进一个全栈AI应用可能包含多个组件前端界面、后端API服务、模型服务Model Serving、向量数据库、特定的数据处理流水线等。如果所有代码都放在一个巨型仓库Monorepo里任何微小的修改都会触发全量的CI/CD依赖管理也会变成噩梦。我们采用多仓管理每个核心组件或服务拥有独立的代码仓库。例如ai-agent-orchestrator负责智能体的流程编排与工具调用。model-service封装对各类大模型API如GPT、Claude或自研模型的调用。knowledge-rag-service处理文档切片、向量化存储与检索增强生成RAG逻辑。frontend-chat-interface用户交互界面。每个仓库有独立的生命周期、版本号和部署流程。通过清晰的接口契约如gRPC协议或REST API规范进行通信。这种模式使得团队可以并行开发技术栈选择也更灵活例如模型服务用Python编排服务用Go。2.2 整体架构视图与数据流基于上述理念我们设计的系统架构是一个清晰的松散耦合分层架构。前端层一个轻量级的Web应用使用React或Vue提供聊天界面并通过WebSocket或HTTP长轮询与后端网关通信。API网关层作为统一的入口点处理用户认证、限流、请求路由。它将用户请求分发到后端的业务编排服务。业务编排层AI Agent Orchestrator这是系统的“大脑”。它接收用户问题决定调用哪个工具如搜索知识库、查询数据库、执行代码管理多轮对话的上下文Context并最终将模型生成的结果格式化后返回。这里会大量运用SDD中定义的Prompt模板和流程逻辑。AI能力服务层这是一个服务集合。模型服务对接云端大模型API或部署本地模型。负责处理Token计算、费用控制、Fallback策略当主模型失败时自动切换备用模型。知识服务RAG管理企业私有知识库。用户提问时从此服务检索最相关的文档片段作为上下文注入给大模型实现精准回答。工具服务提供AI Agent可以调用的具体功能如天气查询、订单状态检索、代码执行沙箱等。每个工具都是一个独立的微服务。数据与基础设施层包括向量数据库如Milvus, Pinecone、关系型数据库、对象存储用于存放模型文件、文档源文件以及由Harness管理的Kubernetes集群所有服务都容器化部署于此。整个数据流是用户输入 - 网关 - 编排器 - 可选调用知识服务检索/调用工具服务执行- 模型服务生成 - 编排器格式化 - 网关 - 用户输出。Harness的流水线覆盖了从代码提交到每个服务容器镜像构建、安全扫描、部署到K8s的全过程。3. 核心实践SDD驱动下的AI需求拆解与设计3.1 如何撰写一份合格的AI项目SDDSDD不是一份空洞的概述而是一份可执行的技术蓝图。对于AI项目我们将其核心章节扩展为1. 业务目标与成功指标目标不是“提升智能客服水平”而是“在机票退改签场景下将AI客服的意图识别准确率从85%提升至95%并将首次解决率提升15%”。成功指标必须可量化。例如自动化测试集包含1000个标注好的用户问法上的意图识别F1-score线上真实对话的用户满意度评分CSAT平均值平均对话轮次越低越好代表效率高。2. 系统架构与组件设计绘制详细的架构图标明各服务边界和通信协议。重点描述AI核心组件Agent类型是单一任务Agent还是基于ReAct或Plan-and-Execute模式的复杂Agent上下文管理上下文窗口多大采用何种摘要或滑动窗口策略来节省Token工具设计每个工具的名称、功能描述、输入/输出JSON Schema、错误处理方式。Prompt工程给出核心Prompt模板包括系统角色设定、少样本示例Few-shot Examples、输出格式指令。3. 数据流与接口定义用序列图描述一次典型用户交互的完整流程。定义所有内部服务间API的详细规范可以使用OpenAPI Specification。4. 非功能性需求性能端到端响应时间P95 3秒。成本平均单次对话Token消耗不超过2000折算成本低于0.01元。可维护性Prompt模板必须版本化、外部化配置如存储在数据库或配置中心支持热更新无需重启服务。安全性用户输入输出过滤、Prompt注入攻击防护、工具调用的权限校验。5. 测试与评估策略单元测试对工具函数、Prompt渲染逻辑进行测试。集成测试模拟用户对话验证整个Agent流程。评估体系除了线上指标建立离线评估流水线定期用最新的测试集跑模型监控性能波动。注意SDD评审会是最关键的环节。必须要求算法工程师、后端工程师、前端工程师、测试工程师和产品经理全部参与。评审的重点是确认接口契约、评估方案的可行性和非功能性需求的合理性。3.2 从SDD到任务拆解与排期一份通过的SDD会直接转化为Jira或类似项目管理工具中的Epic和Story。每个Story对应SDD中的一个可交付模块例如“Story-101: 实现机票退改签意图识别Prompt模板V1.0并在测试集上达到90%准确率”。“Story-102: 开发‘查询订单状态’工具服务提供RESTful API并集成到Agent工具列表”。“Story-103: 搭建Harness流水线实现model-service的自动化构建与部署”。这样整个AI项目就从“探索性实验”转变为“有明确验收标准的工程项目”。4. 基于Harness的AI应用CI/CD流水线构建4.1 流水线设计不止于构建与部署对于AI应用CI/CD流水线需要处理更多特殊工件和步骤。我们为model-service仓库设计的Harness流水线包含以下阶段1. 代码拉取与质量门禁触发Git仓库的main或release/*分支有新的合并请求。步骤代码静态分析SonarQube、安全检查检查依赖漏洞如torch版本是否存在已知CVE。2. 模型资产处理这是AI流水线的特色步骤。如果SDD中定义使用特定微调模型或嵌入模型此步骤负责方案A下载从指定的模型仓库如Hugging Face、公司内部模型库下载指定版本的模型文件使用校验和验证完整性。方案B训练触发一个独立的、资源消耗更大的训练流水线可能运行在GPU集群上训练完成后将产出的模型权重文件归档到对象存储并生成版本元数据。将模型文件打包进Docker镜像的特定目录或准备作为Volume挂载的路径。3. 容器镜像构建与推送使用多阶段构建的Dockerfile以减小最终镜像体积。将上一步处理好的模型资产如果需要复制到镜像中。将镜像推送到私有镜像仓库如Harbor标签包含Git提交哈希和日期。4. 自动化测试单元测试运行Pythonpytest。集成测试部署一个临时测试环境Namespace启动该服务及其依赖如向量数据库模拟器运行集成测试套件验证模型调用和基础功能。5. 安全扫描与合规检查对生成的Docker镜像进行漏洞扫描使用Trivy或Clair。检查镜像中是否包含不合规的许可证或敏感信息。6. 部署到环境金丝雀发布首先将新版本部署到K8s集群中但只将少量如5%的线上流量路由到新版本Pod同时通过Harness集成的监控观察错误率、延迟等指标。渐进式交付如果金丝雀阶段指标正常逐步将流量比例提升至20%、50%、100%。在整个过程中可以随时通过Harness界面一键回滚。7. 后置步骤模型性能监控集成流水线最后一步会更新Harness或关联的可观测性平台如Datadog, Prometheus中的配置确保新部署的服务实例的指标如model_inference_latency_seconds,token_usage_per_request能被正确采集和告警。4.2 环境管理与配置分离我们利用Harness的环境管理和配置覆盖功能为dev、qa、staging、prod分别定义配置。开发环境可能使用较小的模型如text-embedding-3-small和模拟的工具服务以节省成本和加速测试。生产环境使用性能最强的模型如gpt-4-turbo并连接真实的工具和数据库。API密钥、模型端点等敏感信息通过Harness的加密Secret管理绝不硬编码在代码或镜像中。5. 多仓模式下的开发协作与依赖管理5.1 仓库划分原则与接口契约如何划分仓库是个技术活。我们的原则是“高内聚、低耦合”和“独立发布能力”。高内聚一个仓库内的代码应属于同一个明确的业务域或技术域。例如所有与“订单”相关的工具服务查询、创建、取消可以放在一个order-tools仓库。低耦合仓库之间只能通过明确定义的APIHTTP/gRPC或消息队列进行通信禁止直接数据库访问或共享内存等紧耦合方式。独立发布每个仓库应有自己的版本号遵循SemVer并且其修改和发布不应强制要求其他仓库同步更新。接口契约的管理我们使用Protobuf用于gRPC或OpenAPI Spec用于REST来严格定义服务间的接口。这些.proto或.yaml文件存放在一个独立的api-contracts仓库中。所有依赖该接口的服务都通过Git Submodule或包管理工具如将编译后的客户端代码发布到私有PyPI/NPM来引用特定版本的契约。这确保了前后端和不同服务之间的兼容性。5.2 开发工作流与版本协调在多仓模式下一个功能的开发可能涉及多个仓库的改动。我们采用以下工作流创建功能分支在相关的每个仓库如agent-orchestrator和order-tools中基于main分支创建同名功能分支如feature/refund-assistant。同步开发与测试开发者在各自分支上修改代码。本地通过Docker Compose启动一个包含所有依赖服务的完整环境进行集成测试。更新接口契约如果功能需要修改接口首先向api-contracts仓库提交Pull Request评审通过合并后生成新版本的客户端代码。依赖升级在各个服务仓库中更新对api-contracts新版本的依赖。分别发起PR向各个仓库的主分支发起合并请求。每个PR的CI流水线都会运行。协调发布所有PR合并后通过Harness流水线分别部署各个服务。为了功能一致性我们可能会使用功能开关Feature Flag。新功能代码部署后默认关闭待所有相关服务就绪后再通过Harness的功能开关管理界面统一开启。实操心得多仓管理初期会增加一些协调成本但长期来看它带来的模块清晰度、独立可扩展性和技术选代灵活性是巨大的优势。关键在于建立严格的接口契约文化和高效的本地集成测试环境。6. 典型场景实战构建一个智能客服订单查询助手让我们通过一个简化场景串联上述所有实践。目标是构建一个能理解用户自然语言、自动查询订单状态并回复的AI助手。Step 1: SDD撰写与评审我们首先撰写SDD明确工具只有一个get_order_status工具输入订单号返回订单状态、商品信息、物流信息。Prompt设计系统Prompt会定义助手角色并说明“当用户询问订单情况时你必须主动询问或提取订单号然后调用get_order_status工具。”输出要求模型将工具返回的JSON数据转化为一段友好、自然的回复文本。Step 2: 多仓开发在order-tools仓库开发get_order_status工具的gRPC服务。在api-contracts仓库定义该工具的.proto文件。在agent-orchestrator仓库集成api-contracts生成的客户端并在Agent的工具列表中注册该工具编写调用逻辑和结果处理逻辑。在frontend-chat-interface仓库开发聊天界面。Step 3: Harness流水线配置为order-tools和agent-orchestrator分别配置Harness流水线包含构建、测试、安全扫描、金丝雀部署等步骤。在agent-orchestrator的流水线中增加一个“Prompt模板验证”步骤从配置中心拉取最新的Prompt用一组预定义的测试用例如“我的订单12345到哪了”发起模拟请求验证Agent是否能正确调用工具并返回格式正确的回复。Step 4: 集成与发布所有服务通过流水线部署到测试环境。进行端到端集成测试。使用功能开关控制新助手功能。一切就绪后在Harness中打开开关功能灰度上线。7. 避坑指南与效能提升在实践中我们踩过不少坑也总结出一些提升效能的技巧。常见问题与排查Agent无限循环或调用错误工具现象Agent反复调用同一个工具或调用了不相关的工具。排查首先检查SDD中的Prompt设计是否对工具的选择条件描述不清。其次在日志中输出Agent每一步的“思考过程”Chain-of-Thought这是调试Agent行为的最重要依据。可以临时增加日志级别查看模型生成的中间文本。解决优化Prompt提供更清晰的工具描述和调用示例。为工具调用增加防护逻辑比如单轮对话中同一工具最多调用3次。流水线中模型下载超时或失败现象CI/CD流水线在下载数GB的大模型时网络超时。解决不要在每次流水线中都从公网下载。建议在公司内网搭建模型镜像仓库如使用Hugging Face的hf-transfer加速或自建镜像站。流水线从内网镜像站下载速度稳定且可控。多仓开发时本地环境搭建复杂现象开发者需要手动启动五六个服务才能开始调试。解决使用docker-compose.yml或Tilt工具定义完整的本地开发环境。一个命令即可拉起所有依赖服务使用测试版本或模拟器。确保这个配置文件在项目根目录或一个独立的dev-env仓库中维护。效能提升技巧Prompt模板管理不要将Prompt硬编码在代码中。使用数据库或配置中心如Consul, Apollo存储和管理Prompt模板。这样可以在不重启服务的情况下动态调整Prompt进行A/B测试或快速修复问题。Harness的部署功能可以很方便地触发配置更新。测试数据工厂建立丰富的测试用例库不仅包含正向用例更要包含各种边界和对抗性用例如用户输入乱码、故意进行Prompt注入攻击。将这些用例集成到Harness流水线的自动化测试阶段作为质量门禁。成本与性能监控看板在Harness或Grafana中建立专属看板监控每个AI服务的核心指标请求量、平均响应延迟、Token消耗分布、模型调用失败率、各工具调用次数等。设置告警当单次对话成本异常偏高或延迟陡增时能及时通知负责人。“Harness Agent”与“AI Agent”的区分这是一个容易混淆的概念。在我们这个上下文中Harness是一个软件交付平台它内部的“Delegate”可以看作其执行任务的代理一种软件代理。而AI Agent是指具有自主理解、规划和执行能力的人工智能体。二者完全不在一个层面。Harness平台可以用来部署、管理和监控运行AI Agent的服务但本身并不是AI Agent。这次将Harness、SDD和多仓管理融入AI全栈开发的实践让我们深刻体会到AI工程的成熟度直接决定了AI应用能否从“演示原型”走向“稳定生产”。这套组合拳打下来最直观的感受是“可控”。需求变更可控、代码质量可控、发布风险可控、线上表现可控。它或许不是唯一答案但为我们团队在快速变化的AI浪潮中提供了一条稳健前行的工程路径。如果你也在探索AI项目的工程化不妨从一份详尽的SDD和一个自动化的部署流水线开始这会是回报率最高的投入。