1. 项目概述为什么我们需要一个开源的LLMOps平台如果你和我一样在过去一年里深度参与了基于大语言模型的应用开发那你一定经历过这样的场景为了找到一个合适的提示词在Jupyter Notebook里反复修改、手动测试为了评估不同模型或参数的效果不得不写一堆临时脚本结果数据散落在各处难以对比好不容易上线了却发现某个提示词的微小改动导致线上效果暴跌却无法快速定位原因。这些痛点正是LLM应用从“玩具”走向“生产级”过程中每个团队都必须跨越的鸿沟。传统的软件开发有成熟的DevOps工具链从代码管理、CI/CD到监控告警一应俱全。但LLM应用开发呢它更像是一个“手工业”阶段——高度依赖人工调优缺乏标准化的工程实践和工具支持。这就是LLMOps概念兴起的背景。它旨在将DevOps的理念引入LLM应用生命周期实现提示词管理、实验追踪、自动化评估和线上可观测性的闭环。今天要深入探讨的Agenta正是这样一个雄心勃勃的开源LLMOps平台。它不是一个简单的工具而是一个试图将LLM应用开发的“手工作坊”升级为“现代化工厂”的完整解决方案。简单来说Agenta想成为LLM应用领域的“GitLab Datadog MLflow”综合体。它集成了交互式提示词游乐场、版本化的提示词管理、系统化的评估框架以及生产环境下的可观测性追踪。对于工程团队它提供了API和程序化集成能力对于产品经理和领域专家它提供了直观的Web界面进行协作和评估。我最初接触Agenta是因为团队在构建一个智能客服系统时陷入了“提示词地狱”。不同版本的提示词、不同的模型参数、不同来源的测试用例全都混在一起每次AB测试都像是一次冒险。Agenta的出现让我们第一次能够在一个统一的平台上系统地管理整个LLM应用的迭代流程。接下来我将结合近半年的实战经验为你拆解Agenta的核心设计、深度实操以及那些官方文档里不会写的“坑”与技巧。2. 核心架构与设计哲学解析要真正用好一个工具理解其背后的设计思路至关重要。Agenta的架构并非凭空而来它精准地回应了LLM应用工程化中的几个核心挑战。2.1 以“应用”为中心的模型与许多以“模型”或“API调用”为中心的框架不同Agenta的核心抽象是“应用”。一个“应用”在Agenta中是一个可部署的单元它包含了完整的业务逻辑不仅仅是最终的提示词模板还包括可能的前置处理逻辑、对LLM的调用参数如模型、温度、最大令牌数、以及后处理逻辑。这种设计非常符合生产实际。我们很少直接裸调LLM API总是需要一些上下文组装、结果解析或错误处理。Agenta允许你将这一整套逻辑定义为一个Python函数并用装饰器agenta.entrypoint进行标记。这个函数就是你的应用入口。平台会为这个函数自动生成一个Web界面游乐场和一个可调用的API端点。为什么这么设计这解决了LLM应用“配置漂移”的问题。在传统开发中提示词可能在代码里模型参数在环境变量里业务逻辑又散落在各处。Agenta强制你将所有相关配置与逻辑绑定在一个可版本化的“应用”包内确保了从开发、测试到部署环境的一致性。2.2 四支柱功能管理、评估、观测、协作Agenta的功能围绕四大支柱构建这四大支柱构成了LLM应用生命周期的完整闭环提示词管理与工程这不是一个简单的文本编辑器。它是一个支持多版本、分支、环境管理的协作平台。你可以像管理代码一样管理提示词为“开发”、“预发”、“生产”环境设置不同的提示词版本。更重要的是它支持复杂配置模式。这意味着你的提示词可以不是静态文本而是一个包含下拉框、滑块、文本框的交互式表单允许非技术成员如产品经理、运营安全地调整某些参数而无需触碰代码。系统化评估评估是LLM应用的“质量门禁”。Agenta的评估框架支持两种主要方式基于测试集的自动化评估你可以上传CSV或从生产数据中创建测试集。评估器可以是内置的如相关性、忠实度、有毒内容检测也可以是自定义的Python函数甚至是LLM-as-a-Judge用一个大模型来评估另一个模型的输出。所有评估结果被集中记录和可视化方便横向对比不同应用版本的效果。人工反馈集成自动化评估有其局限关键任务仍需人类专家把关。Agenta允许你在界面上直接对模型的输出进行评分和标注这些反馈可以回流用于优化提示词或训练评估器。生产可观测性应用上线只是开始。Agenta集成了OpenTelemetry标准能够自动追踪每一次LLM调用的详细信息使用了哪个提示词版本、调用了哪个模型、消耗了多少Token、花费了多少钱、延迟是多少、输入输出是什么。这些数据通过预置的仪表盘呈现让你能实时监控成本、性能和异常。当线上出现问题时你可以通过追踪链路快速定位是提示词问题、模型问题还是业务逻辑问题。多角色协作这是Agenta区别于纯代码库的关键。它通过Web界面为不同角色提供了入口工程师通过SDK和API集成关注自动化、部署和运维。领域专家/产品经理通过游乐场界面调整提示词和参数运行评估查看结果。团队负责人通过仪表盘总览所有应用的运行状态、成本和性能指标。这种设计将技术栈和非技术栈的协作流程无缝衔接了起来。2.3 技术栈与部署选择Agenta采用微服务架构核心组件包括后端Python (FastAPI)前端React数据库PostgreSQL (存储元数据、评估结果、用户数据)向量数据库Qdrant (可选用于某些高级检索功能)消息队列Redis (用于任务队列如异步评估任务)基础设施全面容器化通过Docker Compose或Kubernetes部署。它提供了两种主要的使用方式Agenta Cloud官方托管的SaaS服务开箱即用适合快速启动和中小团队。自托管提供完整的Docker Compose文件可以在你自己的服务器或私有云上部署满足数据安全和定制化需求。选择哪种方式取决于你的团队规模、安全要求和运维能力。对于大多数想要深度集成到自身开发流程的企业我推荐自托管虽然初期有部署成本但长期来看可控性和灵活性更强。3. 从零到一实战部署与第一个应用创建理论说了这么多我们动手搭一个。这里我以自托管部署为例因为这会涉及更多细节和可能遇到的问题。假设我们有一台Ubuntu 22.04的服务器。3.1 环境准备与部署首先确保服务器已安装Docker和Docker Compose。然后我们克隆代码并启动服务。# 1. 克隆仓库 git clone https://github.com/Agenta-AI/agenta.git cd agenta # 2. 复制并配置环境变量文件 cp hosting/docker-compose/oss/env.oss.gh.example hosting/docker-compose/oss/.env.oss.gh接下来是关键一步编辑.env.oss.gh文件。很多部署失败都源于这里配置不当。# 使用vim或nano编辑 vim hosting/docker-compose/oss/.env.oss.gh你需要关注以下几个核心配置POSTGRES_PASSWORD设置一个强密码这是数据库的根密码。SECRET_KEY用于加密会话务必使用openssl rand -hex 32生成一个随机字符串。BACKEND_URL如果你在本地部署通常是http://localhost。如果部署在远程服务器并有域名则需改为https://your-domain.com。这个配置错误会导致前端无法正确调用后端API。OPENAI_API_KEY如果你计划使用OpenAI的模型在此填入你的API密钥。你也可以后续在UI中添加。实操心得在远程服务器部署时BACKEND_URL和WEB_URL必须配置为外部可访问的地址如服务器公网IP或域名而不能是localhost。同时确保服务器的防火墙开放了80/443端口如果你用Traefik或你自定义的端口。配置完成后启动服务# 3. 启动所有服务-d 表示后台运行 docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web --profile with-traefik up -d这个命令会启动包括Web前端、后端API、数据库、Redis、Traefik反向代理在内的所有服务。首次启动需要拉取镜像可能需要几分钟。启动后访问http://你的服务器IP。如果一切顺利你会看到Agenta的登录界面。默认情况下首次注册的用户会成为管理员。3.2 创建你的第一个LLM应用登录后我们创建一个简单的“邮件助手”应用它能根据用户输入的关键点生成一封结构清晰的商务邮件。首先我们需要在开发机上安装Agenta的Python SDKpip install agenta然后创建一个Python文件例如email_assistant.pyimport agenta as ag from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 初始化LangChain的OpenAI客户端Agenta也原生支持直接调用这里用LangChain示例 llm ChatOpenAI(modelgpt-4o-mini, temperature0.7) # 定义提示词模板。{key_points}和{tone}将是我们在Agenta界面上可调的参数。 prompt_template ChatPromptTemplate.from_messages([ (system, 你是一位专业的商务邮件撰写助手。请根据用户提供的关键点和语气要求撰写一封格式规范、用语得体的邮件。), (human, 关键点{key_points}\n语气要求{tone}\n请生成邮件正文) ]) # 定义处理链 chain prompt_template | llm | StrOutputParser() # 使用Agenta装饰器定义应用入口点 ag.entrypoint def generate_email( key_points: str ag.TextParam(请列出邮件要点用分号隔开), tone: str ag.MultipleChoiceParam(语气, choices[正式, 友好, 紧迫, 委婉], default正式) ) - str: 根据关键点和语气生成商务邮件。 # 调用LangChain处理链 result chain.invoke({ key_points: key_points, tone: tone }) return result代码写好了如何把它变成Agenta里的一个“应用”使用Agenta CLI# 确保你在Python文件所在目录并且已经通过 agenta init 初始化过项目会生成agenta.yaml配置 agenta init # 如果还没初始化 # 将你的应用推送到Agenta服务器 agenta deploy email_assistant.py --app_name 商务邮件助手 --backend_url http://你的服务器IP/api执行deploy命令后Agenta SDK会做几件事将你的代码和依赖关系打包。在Agenta后端注册这个应用。自动为这个应用生成一个Web游乐场界面。现在回到Agenta的Web界面在“应用”列表里你应该能看到刚创建的“商务邮件助手”。点击进入你会看到一个交互式界面左侧是你可以调整的参数key_points文本框和tone下拉框右侧是模型输出区域。你可以随意调整参数点击“运行”实时看到不同提示词和参数下的输出结果。这就是Agenta的核心魔力它将一个Python函数瞬间变成了一个可交互、可配置、可版本化的LLM应用服务。4. 深入核心功能提示词管理、评估与观测实战应用创建好了接下来看看如何利用Agenta的三大核心功能来迭代和优化它。4.1 提示词工程与版本管理在“商务邮件助手”的游乐场里你调整参数并运行得到了一个不错的输出。你想保存这个“配方”。点击“保存为版本”给它起个名字比如v1_formal。现在你对提示词做了修改想让语气更友好一些。你调整了系统提示词加入了“请使用更亲切、自然的措辞”。测试效果也不错于是你保存为另一个版本v2_friendly。此时在应用的“版本”页面你可以看到所有保存的版本就像Git的历史记录一样。你可以比较不同版本的输出甚至可以将某个版本“发布”到“生产”环境。这意味着你的后端API在调用这个应用时将固定使用“生产”环境指定的提示词版本从而保证了线上服务的稳定性。复杂配置实战假设我们想让邮件长度也可调。我们可以修改代码ag.entrypoint def generate_email( key_points: str ag.TextParam(请列出邮件要点用分号隔开), tone: str ag.MultipleChoiceParam(语气, choices[正式, 友好, 紧迫, 委婉], default正式), length: str ag.FloatParam(长度控制, min_value0.5, max_value2.0, default1.0) # 0.5倍到2.0倍长度 ) - str: # 在提示词中融入长度控制 length_instruction 邮件篇幅适中。 if length 1.0 else f请将邮件内容控制在通常篇幅的{length}倍左右。 prompt_template ChatPromptTemplate.from_messages([ (system, f你是一位专业的商务邮件撰写助手。{length_instruction}请根据用户提供的关键点和语气要求撰写一封格式规范、用语得体的邮件。), (human, 关键点{key_points}\n语气要求{tone}\n请生成邮件正文) ]) # ... 其余代码不变重新部署后界面上会多出一个滑块来控制长度。这样产品经理就可以在不接触代码的情况下探索“长度”这个参数对结果的影响。4.2 构建评估体系从主观判断到数据驱动“哪个版本更好”这是一个需要数据回答的问题。我们进入“评估”模块。第一步创建测试集。你可以手动创建也可以从之前的游乐场运行记录中导入或者上传一个CSV文件。假设我们有一个test_cases.csvkey_points,tone,expected_length “项目延期一周需要客户理解附上新的时间表”,正式,中 “邀请参加下周产品研讨会提供会议链接征集议题”,友好,短 “付款提醒账单已逾期请尽快处理”,紧迫,短第二步选择评估器。Agenta提供了多种开箱即用的评估器例如答案相关性评估输出是否与输入关键点相关。语言风格匹配评估输出语气是否符合要求如正式、友好。有害内容检测。自定义评估器我们可以写一个Python函数来评估“邮件长度”import agenta as ag from typing import Dict, Any ag.evaluator def evaluate_email_length(output: str, expected_length: str, **kwargs) - Dict[str, Any]: 评估邮件长度是否符合预期。 expected_length: ‘短‘ ‘中‘ ‘长‘ word_count len(output.split()) score 0 feedback if expected_length 短 and word_count 50: score 1 feedback 长度符合‘短‘的要求。 elif expected_length 中 and 50 word_count 150: score 1 feedback 长度符合‘中‘的要求。 elif expected_length 长 and word_count 150: score 1 feedback 长度符合‘长‘的要求。 else: feedback f长度不符合预期。字数{word_count}预期{expected_length} return { score: score, # 0或1 feedback: feedback }将这个评估器函数也部署到Agenta。现在在创建评估任务时你就可以选择这个自定义的evaluate_email_length评估器并映射expected_length字段到测试集的列。第三步运行评估并分析。选择应用版本比如v1_formal和v2_friendly选择测试集和评估器启动评估。Agenta会异步运行所有测试用例并生成一份详细的评估报告。报告会以表格和图表形式展示每个版本在各个评估维度上的得分。你可以清晰地看到v2_friendly在“友好”语气的测试用例上得分更高但在“正式”邮件上可能略逊一筹。这种数据驱动的比较远比“我感觉这个更好”有说服力。4.3 集成与生产可观测性当你的“商务邮件助手”通过评估准备集成到真正的业务系统比如一个CRM系统时你需要通过API调用它。Agenta为每个应用版本提供了唯一的API端点。你可以在应用设置中找到它格式类似于http://你的服务器IP/api/apps/{app_id}/versions/{version_id}/generate调用方式非常简单curl -X POST http://你的服务器IP/api/apps/your_app_id/versions/production/generate \ -H Content-Type: application/json \ -d { key_points: 项目里程碑达成感谢团队努力安排庆祝活动, tone: 友好 }所有通过此端点的调用都会被Agenta的可观测性模块自动追踪。你可以在“观测”仪表盘中看到总览调用量、平均延迟、错误率、总成本如果模型是计费的。追踪每一次调用的详细链路包括输入的参数、使用的提示词版本、调用的模型、消耗的Token、输出的内容、延迟时间。分析可以按时间、按版本、按输入参数进行筛选和分析。例如你可以发现当key_points超过5条时延迟显著上升或者某种语气下更容易产生格式错误的输出。一个真实的排查案例我们曾发现线上邮件生成突然变慢。通过Agenta的追踪我们快速定位到是因为某个用户输入了极长的关键点列表超过1000字导致提示词Token数暴涨触发了模型的上下文长度限制从而引起了异常处理和重试。我们随后在应用逻辑中增加了输入长度校验和截断问题得以解决。没有这样的追踪这种问题就像大海捞针。5. 高级技巧与避坑指南经过几个月的深度使用我总结了一些能极大提升效率的技巧和常见的“坑”。5.1 提示词管理的最佳实践使用“配置模式”解放开发者将业务逻辑中可能变化的因素如温度、系统提示词前缀、输出格式要求都设计成配置参数。这样非技术成员可以在安全范围内进行优化而无需频繁打扰开发者重新部署代码。善用“分支”和“环境”为“功能开发”、“A/B测试”、“生产”创建不同的分支和环境。确保开发中的改动不会影响线上稳定版本。给版本起有意义的名字不要用v1,v2而是用add_length_control,optimize_for_friendly_tone这样的名字一目了然。5.2 评估体系构建心得评估器贵精不贵多一开始不要追求大而全的评估体系。选择1-3个最核心、最能代表业务成功与否的指标例如对于摘要应用是“信息保留度”对于分类应用是“准确率”。先把它做准、做稳。LLM-as-a-Judge的双刃剑用GPT-4来评估其他模型的输出非常强大但成本高、速度慢且其评判标准可能不稳定。建议将其用于对少量关键样本的最终校验或用于生成训练其他轻量级评估器如规则或小模型的标注数据。测试集要代表真实分布你的测试集应该尽可能模拟线上真实流量的分布。如果线上80%的请求是简单查询那测试集也应该是这个比例。从生产日志中采样构建测试集是一个好方法。5.3 部署与运维中的坑资源规划Agenta的自托管服务默认使用Docker Compose所有服务跑在一台机器上。对于生产环境建议将PostgreSQL、Redis等有状态服务分离部署并做好数据备份。评估任务比较耗资源可以考虑配置独立的Worker节点。网络与配置如前所述BACKEND_URL和WEB_URL的配置是部署失败的头号元凶。在云环境或Kubernetes中要特别注意服务发现和内部通信。升级策略关注Agenta的版本发布但生产环境升级前务必在测试环境充分验证。平台的数据库迁移有时会引入不兼容改动。5.4 与现有工作流集成CI/CD流水线你可以将Agenta的评估API集成到你的CI/CD流程中。例如在合并代码前自动部署新版本的应用并对预设的测试集运行评估只有通过评估如得分高于阈值的版本才能被标记为“可发布”。与现有监控告警整合Agenta提供了OpenTelemetry数据你可以将其导出到Jaeger、Zipkin或你的现有APM如Datadog, New Relic中实现统一的监控视图。6. 横向对比与适用场景市面上LLMOps工具不少如Weights Biases Prompts、LangSmith、Phoenix等。Agenta的独特优势在于它的全栈性和开源可定制。vs LangSmithLangSmith更侧重于为LangChain应用提供调试和追踪与LangChain生态绑定深更像一个强大的开发调试工具。Agenta的应用范围更广不限于LangChain且提供了更完整的提示词管理、团队协作和评估工作流更像一个面向产品全生命期的平台。vs 自研脚本自研脚本灵活但难以维护、无法协作、不易沉淀知识。Agenta将最佳实践产品化提供了开箱即用的UI和API降低了团队的整体认知负担和协作成本。Agenta最适合什么样的团队中小型创业公司或产品团队需要快速构建和迭代LLM应用但缺乏资源搭建一整套内部工具链。Agenta Cloud的免费 tier 是绝佳的起点。中大型企业中对数据安全有要求的团队需要将LLM应用部署在私有环境Agenta的开源版本提供了完整控制权。需要跨职能工程、产品、领域专家紧密协作的团队Agenta的Web界面极大地降低了非技术成员参与LLM优化的门槛。7. 总结与个人体会回顾这半年使用Agenta的经历它确实将我们从“提示词炼金术”的混乱中拯救了出来。最大的改变是LLM应用的迭代从一种艺术变成了可度量、可复现的工程过程。以前优化一个模型效果需要工程师手动改代码、跑脚本、对比结果效率低下且过程不可追溯。现在产品经理可以直接在游乐场里调整参数并看到实时效果保存为一个新版本工程师可以一键触发基于完整测试集的自动化评估用数据报告决定哪个版本更优运维同学可以在统一的仪表盘上监控所有线上LLM调用的健康度和成本。当然Agenta作为一个快速发展的开源项目也有其不完美之处。它的文档虽然全面但深度示例可以更多某些高级功能如复杂的自定义评估器对新手有一定学习曲线自托管的运维复杂度不低。但它的社区非常活跃团队响应迅速我们在使用中遇到的问题基本都能在GitHub Issues或Slack社区中找到答案或得到及时回复。如果你正在严肃地考虑将LLM应用投入生产我强烈建议你花一个下午时间无论是试用Agenta Cloud还是本地部署它的开源版本亲身体验一下它带来的工作流变革。它可能不会解决你所有的问题但它为你提供了一个坚实的、可扩展的工程基础让你能更专注于业务逻辑和创新而不是重复造轮子和陷入运维泥潭。最后一个小建议从一个小而具体的应用开始。不要试图一上来就用Agenta管理你所有的LLM场景。先选一个痛点最明显的用例比如一个关键的文本生成或分类任务用它走完“开发-评估-部署-观测”的全流程。当你和你的团队熟悉了这个工作流感受到了它带来的效率提升和风险降低再逐步推广到其他场景就会顺利得多。
开源LLMOps平台Agenta实战：从提示词管理到生产部署全解析
发布时间：2026/7/26 4:40:03
1. 项目概述为什么我们需要一个开源的LLMOps平台如果你和我一样在过去一年里深度参与了基于大语言模型的应用开发那你一定经历过这样的场景为了找到一个合适的提示词在Jupyter Notebook里反复修改、手动测试为了评估不同模型或参数的效果不得不写一堆临时脚本结果数据散落在各处难以对比好不容易上线了却发现某个提示词的微小改动导致线上效果暴跌却无法快速定位原因。这些痛点正是LLM应用从“玩具”走向“生产级”过程中每个团队都必须跨越的鸿沟。传统的软件开发有成熟的DevOps工具链从代码管理、CI/CD到监控告警一应俱全。但LLM应用开发呢它更像是一个“手工业”阶段——高度依赖人工调优缺乏标准化的工程实践和工具支持。这就是LLMOps概念兴起的背景。它旨在将DevOps的理念引入LLM应用生命周期实现提示词管理、实验追踪、自动化评估和线上可观测性的闭环。今天要深入探讨的Agenta正是这样一个雄心勃勃的开源LLMOps平台。它不是一个简单的工具而是一个试图将LLM应用开发的“手工作坊”升级为“现代化工厂”的完整解决方案。简单来说Agenta想成为LLM应用领域的“GitLab Datadog MLflow”综合体。它集成了交互式提示词游乐场、版本化的提示词管理、系统化的评估框架以及生产环境下的可观测性追踪。对于工程团队它提供了API和程序化集成能力对于产品经理和领域专家它提供了直观的Web界面进行协作和评估。我最初接触Agenta是因为团队在构建一个智能客服系统时陷入了“提示词地狱”。不同版本的提示词、不同的模型参数、不同来源的测试用例全都混在一起每次AB测试都像是一次冒险。Agenta的出现让我们第一次能够在一个统一的平台上系统地管理整个LLM应用的迭代流程。接下来我将结合近半年的实战经验为你拆解Agenta的核心设计、深度实操以及那些官方文档里不会写的“坑”与技巧。2. 核心架构与设计哲学解析要真正用好一个工具理解其背后的设计思路至关重要。Agenta的架构并非凭空而来它精准地回应了LLM应用工程化中的几个核心挑战。2.1 以“应用”为中心的模型与许多以“模型”或“API调用”为中心的框架不同Agenta的核心抽象是“应用”。一个“应用”在Agenta中是一个可部署的单元它包含了完整的业务逻辑不仅仅是最终的提示词模板还包括可能的前置处理逻辑、对LLM的调用参数如模型、温度、最大令牌数、以及后处理逻辑。这种设计非常符合生产实际。我们很少直接裸调LLM API总是需要一些上下文组装、结果解析或错误处理。Agenta允许你将这一整套逻辑定义为一个Python函数并用装饰器agenta.entrypoint进行标记。这个函数就是你的应用入口。平台会为这个函数自动生成一个Web界面游乐场和一个可调用的API端点。为什么这么设计这解决了LLM应用“配置漂移”的问题。在传统开发中提示词可能在代码里模型参数在环境变量里业务逻辑又散落在各处。Agenta强制你将所有相关配置与逻辑绑定在一个可版本化的“应用”包内确保了从开发、测试到部署环境的一致性。2.2 四支柱功能管理、评估、观测、协作Agenta的功能围绕四大支柱构建这四大支柱构成了LLM应用生命周期的完整闭环提示词管理与工程这不是一个简单的文本编辑器。它是一个支持多版本、分支、环境管理的协作平台。你可以像管理代码一样管理提示词为“开发”、“预发”、“生产”环境设置不同的提示词版本。更重要的是它支持复杂配置模式。这意味着你的提示词可以不是静态文本而是一个包含下拉框、滑块、文本框的交互式表单允许非技术成员如产品经理、运营安全地调整某些参数而无需触碰代码。系统化评估评估是LLM应用的“质量门禁”。Agenta的评估框架支持两种主要方式基于测试集的自动化评估你可以上传CSV或从生产数据中创建测试集。评估器可以是内置的如相关性、忠实度、有毒内容检测也可以是自定义的Python函数甚至是LLM-as-a-Judge用一个大模型来评估另一个模型的输出。所有评估结果被集中记录和可视化方便横向对比不同应用版本的效果。人工反馈集成自动化评估有其局限关键任务仍需人类专家把关。Agenta允许你在界面上直接对模型的输出进行评分和标注这些反馈可以回流用于优化提示词或训练评估器。生产可观测性应用上线只是开始。Agenta集成了OpenTelemetry标准能够自动追踪每一次LLM调用的详细信息使用了哪个提示词版本、调用了哪个模型、消耗了多少Token、花费了多少钱、延迟是多少、输入输出是什么。这些数据通过预置的仪表盘呈现让你能实时监控成本、性能和异常。当线上出现问题时你可以通过追踪链路快速定位是提示词问题、模型问题还是业务逻辑问题。多角色协作这是Agenta区别于纯代码库的关键。它通过Web界面为不同角色提供了入口工程师通过SDK和API集成关注自动化、部署和运维。领域专家/产品经理通过游乐场界面调整提示词和参数运行评估查看结果。团队负责人通过仪表盘总览所有应用的运行状态、成本和性能指标。这种设计将技术栈和非技术栈的协作流程无缝衔接了起来。2.3 技术栈与部署选择Agenta采用微服务架构核心组件包括后端Python (FastAPI)前端React数据库PostgreSQL (存储元数据、评估结果、用户数据)向量数据库Qdrant (可选用于某些高级检索功能)消息队列Redis (用于任务队列如异步评估任务)基础设施全面容器化通过Docker Compose或Kubernetes部署。它提供了两种主要的使用方式Agenta Cloud官方托管的SaaS服务开箱即用适合快速启动和中小团队。自托管提供完整的Docker Compose文件可以在你自己的服务器或私有云上部署满足数据安全和定制化需求。选择哪种方式取决于你的团队规模、安全要求和运维能力。对于大多数想要深度集成到自身开发流程的企业我推荐自托管虽然初期有部署成本但长期来看可控性和灵活性更强。3. 从零到一实战部署与第一个应用创建理论说了这么多我们动手搭一个。这里我以自托管部署为例因为这会涉及更多细节和可能遇到的问题。假设我们有一台Ubuntu 22.04的服务器。3.1 环境准备与部署首先确保服务器已安装Docker和Docker Compose。然后我们克隆代码并启动服务。# 1. 克隆仓库 git clone https://github.com/Agenta-AI/agenta.git cd agenta # 2. 复制并配置环境变量文件 cp hosting/docker-compose/oss/env.oss.gh.example hosting/docker-compose/oss/.env.oss.gh接下来是关键一步编辑.env.oss.gh文件。很多部署失败都源于这里配置不当。# 使用vim或nano编辑 vim hosting/docker-compose/oss/.env.oss.gh你需要关注以下几个核心配置POSTGRES_PASSWORD设置一个强密码这是数据库的根密码。SECRET_KEY用于加密会话务必使用openssl rand -hex 32生成一个随机字符串。BACKEND_URL如果你在本地部署通常是http://localhost。如果部署在远程服务器并有域名则需改为https://your-domain.com。这个配置错误会导致前端无法正确调用后端API。OPENAI_API_KEY如果你计划使用OpenAI的模型在此填入你的API密钥。你也可以后续在UI中添加。实操心得在远程服务器部署时BACKEND_URL和WEB_URL必须配置为外部可访问的地址如服务器公网IP或域名而不能是localhost。同时确保服务器的防火墙开放了80/443端口如果你用Traefik或你自定义的端口。配置完成后启动服务# 3. 启动所有服务-d 表示后台运行 docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web --profile with-traefik up -d这个命令会启动包括Web前端、后端API、数据库、Redis、Traefik反向代理在内的所有服务。首次启动需要拉取镜像可能需要几分钟。启动后访问http://你的服务器IP。如果一切顺利你会看到Agenta的登录界面。默认情况下首次注册的用户会成为管理员。3.2 创建你的第一个LLM应用登录后我们创建一个简单的“邮件助手”应用它能根据用户输入的关键点生成一封结构清晰的商务邮件。首先我们需要在开发机上安装Agenta的Python SDKpip install agenta然后创建一个Python文件例如email_assistant.pyimport agenta as ag from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 初始化LangChain的OpenAI客户端Agenta也原生支持直接调用这里用LangChain示例 llm ChatOpenAI(modelgpt-4o-mini, temperature0.7) # 定义提示词模板。{key_points}和{tone}将是我们在Agenta界面上可调的参数。 prompt_template ChatPromptTemplate.from_messages([ (system, 你是一位专业的商务邮件撰写助手。请根据用户提供的关键点和语气要求撰写一封格式规范、用语得体的邮件。), (human, 关键点{key_points}\n语气要求{tone}\n请生成邮件正文) ]) # 定义处理链 chain prompt_template | llm | StrOutputParser() # 使用Agenta装饰器定义应用入口点 ag.entrypoint def generate_email( key_points: str ag.TextParam(请列出邮件要点用分号隔开), tone: str ag.MultipleChoiceParam(语气, choices[正式, 友好, 紧迫, 委婉], default正式) ) - str: 根据关键点和语气生成商务邮件。 # 调用LangChain处理链 result chain.invoke({ key_points: key_points, tone: tone }) return result代码写好了如何把它变成Agenta里的一个“应用”使用Agenta CLI# 确保你在Python文件所在目录并且已经通过 agenta init 初始化过项目会生成agenta.yaml配置 agenta init # 如果还没初始化 # 将你的应用推送到Agenta服务器 agenta deploy email_assistant.py --app_name 商务邮件助手 --backend_url http://你的服务器IP/api执行deploy命令后Agenta SDK会做几件事将你的代码和依赖关系打包。在Agenta后端注册这个应用。自动为这个应用生成一个Web游乐场界面。现在回到Agenta的Web界面在“应用”列表里你应该能看到刚创建的“商务邮件助手”。点击进入你会看到一个交互式界面左侧是你可以调整的参数key_points文本框和tone下拉框右侧是模型输出区域。你可以随意调整参数点击“运行”实时看到不同提示词和参数下的输出结果。这就是Agenta的核心魔力它将一个Python函数瞬间变成了一个可交互、可配置、可版本化的LLM应用服务。4. 深入核心功能提示词管理、评估与观测实战应用创建好了接下来看看如何利用Agenta的三大核心功能来迭代和优化它。4.1 提示词工程与版本管理在“商务邮件助手”的游乐场里你调整参数并运行得到了一个不错的输出。你想保存这个“配方”。点击“保存为版本”给它起个名字比如v1_formal。现在你对提示词做了修改想让语气更友好一些。你调整了系统提示词加入了“请使用更亲切、自然的措辞”。测试效果也不错于是你保存为另一个版本v2_friendly。此时在应用的“版本”页面你可以看到所有保存的版本就像Git的历史记录一样。你可以比较不同版本的输出甚至可以将某个版本“发布”到“生产”环境。这意味着你的后端API在调用这个应用时将固定使用“生产”环境指定的提示词版本从而保证了线上服务的稳定性。复杂配置实战假设我们想让邮件长度也可调。我们可以修改代码ag.entrypoint def generate_email( key_points: str ag.TextParam(请列出邮件要点用分号隔开), tone: str ag.MultipleChoiceParam(语气, choices[正式, 友好, 紧迫, 委婉], default正式), length: str ag.FloatParam(长度控制, min_value0.5, max_value2.0, default1.0) # 0.5倍到2.0倍长度 ) - str: # 在提示词中融入长度控制 length_instruction 邮件篇幅适中。 if length 1.0 else f请将邮件内容控制在通常篇幅的{length}倍左右。 prompt_template ChatPromptTemplate.from_messages([ (system, f你是一位专业的商务邮件撰写助手。{length_instruction}请根据用户提供的关键点和语气要求撰写一封格式规范、用语得体的邮件。), (human, 关键点{key_points}\n语气要求{tone}\n请生成邮件正文) ]) # ... 其余代码不变重新部署后界面上会多出一个滑块来控制长度。这样产品经理就可以在不接触代码的情况下探索“长度”这个参数对结果的影响。4.2 构建评估体系从主观判断到数据驱动“哪个版本更好”这是一个需要数据回答的问题。我们进入“评估”模块。第一步创建测试集。你可以手动创建也可以从之前的游乐场运行记录中导入或者上传一个CSV文件。假设我们有一个test_cases.csvkey_points,tone,expected_length “项目延期一周需要客户理解附上新的时间表”,正式,中 “邀请参加下周产品研讨会提供会议链接征集议题”,友好,短 “付款提醒账单已逾期请尽快处理”,紧迫,短第二步选择评估器。Agenta提供了多种开箱即用的评估器例如答案相关性评估输出是否与输入关键点相关。语言风格匹配评估输出语气是否符合要求如正式、友好。有害内容检测。自定义评估器我们可以写一个Python函数来评估“邮件长度”import agenta as ag from typing import Dict, Any ag.evaluator def evaluate_email_length(output: str, expected_length: str, **kwargs) - Dict[str, Any]: 评估邮件长度是否符合预期。 expected_length: ‘短‘ ‘中‘ ‘长‘ word_count len(output.split()) score 0 feedback if expected_length 短 and word_count 50: score 1 feedback 长度符合‘短‘的要求。 elif expected_length 中 and 50 word_count 150: score 1 feedback 长度符合‘中‘的要求。 elif expected_length 长 and word_count 150: score 1 feedback 长度符合‘长‘的要求。 else: feedback f长度不符合预期。字数{word_count}预期{expected_length} return { score: score, # 0或1 feedback: feedback }将这个评估器函数也部署到Agenta。现在在创建评估任务时你就可以选择这个自定义的evaluate_email_length评估器并映射expected_length字段到测试集的列。第三步运行评估并分析。选择应用版本比如v1_formal和v2_friendly选择测试集和评估器启动评估。Agenta会异步运行所有测试用例并生成一份详细的评估报告。报告会以表格和图表形式展示每个版本在各个评估维度上的得分。你可以清晰地看到v2_friendly在“友好”语气的测试用例上得分更高但在“正式”邮件上可能略逊一筹。这种数据驱动的比较远比“我感觉这个更好”有说服力。4.3 集成与生产可观测性当你的“商务邮件助手”通过评估准备集成到真正的业务系统比如一个CRM系统时你需要通过API调用它。Agenta为每个应用版本提供了唯一的API端点。你可以在应用设置中找到它格式类似于http://你的服务器IP/api/apps/{app_id}/versions/{version_id}/generate调用方式非常简单curl -X POST http://你的服务器IP/api/apps/your_app_id/versions/production/generate \ -H Content-Type: application/json \ -d { key_points: 项目里程碑达成感谢团队努力安排庆祝活动, tone: 友好 }所有通过此端点的调用都会被Agenta的可观测性模块自动追踪。你可以在“观测”仪表盘中看到总览调用量、平均延迟、错误率、总成本如果模型是计费的。追踪每一次调用的详细链路包括输入的参数、使用的提示词版本、调用的模型、消耗的Token、输出的内容、延迟时间。分析可以按时间、按版本、按输入参数进行筛选和分析。例如你可以发现当key_points超过5条时延迟显著上升或者某种语气下更容易产生格式错误的输出。一个真实的排查案例我们曾发现线上邮件生成突然变慢。通过Agenta的追踪我们快速定位到是因为某个用户输入了极长的关键点列表超过1000字导致提示词Token数暴涨触发了模型的上下文长度限制从而引起了异常处理和重试。我们随后在应用逻辑中增加了输入长度校验和截断问题得以解决。没有这样的追踪这种问题就像大海捞针。5. 高级技巧与避坑指南经过几个月的深度使用我总结了一些能极大提升效率的技巧和常见的“坑”。5.1 提示词管理的最佳实践使用“配置模式”解放开发者将业务逻辑中可能变化的因素如温度、系统提示词前缀、输出格式要求都设计成配置参数。这样非技术成员可以在安全范围内进行优化而无需频繁打扰开发者重新部署代码。善用“分支”和“环境”为“功能开发”、“A/B测试”、“生产”创建不同的分支和环境。确保开发中的改动不会影响线上稳定版本。给版本起有意义的名字不要用v1,v2而是用add_length_control,optimize_for_friendly_tone这样的名字一目了然。5.2 评估体系构建心得评估器贵精不贵多一开始不要追求大而全的评估体系。选择1-3个最核心、最能代表业务成功与否的指标例如对于摘要应用是“信息保留度”对于分类应用是“准确率”。先把它做准、做稳。LLM-as-a-Judge的双刃剑用GPT-4来评估其他模型的输出非常强大但成本高、速度慢且其评判标准可能不稳定。建议将其用于对少量关键样本的最终校验或用于生成训练其他轻量级评估器如规则或小模型的标注数据。测试集要代表真实分布你的测试集应该尽可能模拟线上真实流量的分布。如果线上80%的请求是简单查询那测试集也应该是这个比例。从生产日志中采样构建测试集是一个好方法。5.3 部署与运维中的坑资源规划Agenta的自托管服务默认使用Docker Compose所有服务跑在一台机器上。对于生产环境建议将PostgreSQL、Redis等有状态服务分离部署并做好数据备份。评估任务比较耗资源可以考虑配置独立的Worker节点。网络与配置如前所述BACKEND_URL和WEB_URL的配置是部署失败的头号元凶。在云环境或Kubernetes中要特别注意服务发现和内部通信。升级策略关注Agenta的版本发布但生产环境升级前务必在测试环境充分验证。平台的数据库迁移有时会引入不兼容改动。5.4 与现有工作流集成CI/CD流水线你可以将Agenta的评估API集成到你的CI/CD流程中。例如在合并代码前自动部署新版本的应用并对预设的测试集运行评估只有通过评估如得分高于阈值的版本才能被标记为“可发布”。与现有监控告警整合Agenta提供了OpenTelemetry数据你可以将其导出到Jaeger、Zipkin或你的现有APM如Datadog, New Relic中实现统一的监控视图。6. 横向对比与适用场景市面上LLMOps工具不少如Weights Biases Prompts、LangSmith、Phoenix等。Agenta的独特优势在于它的全栈性和开源可定制。vs LangSmithLangSmith更侧重于为LangChain应用提供调试和追踪与LangChain生态绑定深更像一个强大的开发调试工具。Agenta的应用范围更广不限于LangChain且提供了更完整的提示词管理、团队协作和评估工作流更像一个面向产品全生命期的平台。vs 自研脚本自研脚本灵活但难以维护、无法协作、不易沉淀知识。Agenta将最佳实践产品化提供了开箱即用的UI和API降低了团队的整体认知负担和协作成本。Agenta最适合什么样的团队中小型创业公司或产品团队需要快速构建和迭代LLM应用但缺乏资源搭建一整套内部工具链。Agenta Cloud的免费 tier 是绝佳的起点。中大型企业中对数据安全有要求的团队需要将LLM应用部署在私有环境Agenta的开源版本提供了完整控制权。需要跨职能工程、产品、领域专家紧密协作的团队Agenta的Web界面极大地降低了非技术成员参与LLM优化的门槛。7. 总结与个人体会回顾这半年使用Agenta的经历它确实将我们从“提示词炼金术”的混乱中拯救了出来。最大的改变是LLM应用的迭代从一种艺术变成了可度量、可复现的工程过程。以前优化一个模型效果需要工程师手动改代码、跑脚本、对比结果效率低下且过程不可追溯。现在产品经理可以直接在游乐场里调整参数并看到实时效果保存为一个新版本工程师可以一键触发基于完整测试集的自动化评估用数据报告决定哪个版本更优运维同学可以在统一的仪表盘上监控所有线上LLM调用的健康度和成本。当然Agenta作为一个快速发展的开源项目也有其不完美之处。它的文档虽然全面但深度示例可以更多某些高级功能如复杂的自定义评估器对新手有一定学习曲线自托管的运维复杂度不低。但它的社区非常活跃团队响应迅速我们在使用中遇到的问题基本都能在GitHub Issues或Slack社区中找到答案或得到及时回复。如果你正在严肃地考虑将LLM应用投入生产我强烈建议你花一个下午时间无论是试用Agenta Cloud还是本地部署它的开源版本亲身体验一下它带来的工作流变革。它可能不会解决你所有的问题但它为你提供了一个坚实的、可扩展的工程基础让你能更专注于业务逻辑和创新而不是重复造轮子和陷入运维泥潭。最后一个小建议从一个小而具体的应用开始。不要试图一上来就用Agenta管理你所有的LLM场景。先选一个痛点最明显的用例比如一个关键的文本生成或分类任务用它走完“开发-评估-部署-观测”的全流程。当你和你的团队熟悉了这个工作流感受到了它带来的效率提升和风险降低再逐步推广到其他场景就会顺利得多。
技术解析：从Transformer架构到实战应用)
