最近在尝试把一些AI能力落地到真实业务里发现一个挺有意思的现象很多团队能把一个Demo跑得飞快但一到要稳定、可评估、能迭代的工程化阶段就卡住了。问题往往不是出在模型本身而是整个流程——怎么管理上下文、怎么追踪每次调用的输入输出、怎么评估效果、怎么把一次性的脚本变成可维护的服务。正好最近在探索一个结合了Harness架构和Langfuse的财务分析智能体项目。这听起来像是一个很具体的工具组合但它的核心价值其实是提供了一个从“单次实验”到“企业级评估平台”的完整工程化路径。很多人一听到“企业级”、“工程化”就觉得头大觉得要搞一堆复杂的K8s、微服务、监控告警。其实没那么复杂真正的工程化第一步往往是把那些“黑盒”操作变得透明、可追溯、可度量。这个项目就是一个很好的切入点。它不只是一个教程更像是一个方法论如何用相对轻量的工具链构建一个具备生产可用性的AI智能体并且从一开始就内置了评估和迭代的能力。下面我们就抛开那些宏大的概念从一次具体的“财务报告分析”任务出发看看这条路径到底该怎么走。1. 先别急着写Agent理解“工程化”到底要解决什么问题在开始安装任何工具、写第一行代码之前我们需要先达成一个共识为什么单纯的脚本或Notebook不够用当我们说“企业级AI工程化”时我们到底在怕什么假设你写了一个基于大模型的财务分析脚本。输入一份上市公司年报PDF它能输出一份结构化的分析报告包括盈利能力、偿债能力、运营效率等维度。作为一次性的演示这很棒。但如果你想让它成为团队每周分析十家公司、持续优化模型提示词、并且能向老板证明其分析准确性的一个服务问题就来了问题一不可复现。今天跑的结果很好明天同样的输入因为模型服务的轻微波动或上下文窗口的微妙差异输出可能天差地别。你无法向同事证明“上周那个精彩的分析是稳定可得的”。问题二黑盒操作。模型内部发生了什么你给的提示词Prompt到底哪部分起了关键作用是系统指令生效了还是后面追加的用户指令覆盖了前者当分析结果出现偏差时你没有任何线索去排查。问题三评估困难。你怎么知道这次的分析比上次好是靠人肉阅读对比吗如何量化“分析深度”或“覆盖完整性”没有数据任何关于“优化”的讨论都是空中楼阁。问题四协作灾难。你想优化提示词于是复制了一份脚本改了几个参数。你的同事也在改。很快你们就有了十几个版本各异的脚本没人知道哪个版本对应哪次的最佳结果合并和回溯成为噩梦。Harness架构和Langfuse这个组合瞄准的正是这四个痛点。它们的核心分工可以这样理解Harness负责“智能体工作流的编排与执行”。它把“读取PDF - 解析文本 - 分章节分析 - 汇总报告”这一系列步骤变成一个可视化、可配置、可调度的标准化流程Pipeline。它确保了流程的稳定性和可重复性。Langfuse负责“每一次AI调用的观测与评估”。它像是一个飞行数据记录仪黑匣子自动记录每一次调用大模型的详细日志输入了什么、输出了什么、消耗了多少Token、耗时多长。更重要的是它允许你基于这些记录打上人工或自动的评分比如分析准确性1-5分从而为优化提供数据基础。所以这个项目的起点不是某个酷炫的AI功能而是一个可观测、可评估、可迭代的标准化工作流。先把这个架子搭好再往里面填充具体的分析能力你会发现自己对整个系统的掌控力完全不一样。2. 搭建地基从零开始配置Harness与Langfuse环境理解了“为什么”我们再来看“怎么做”。环境搭建是第一步也是最容易让人放弃的一步。我们的目标不是追求最炫技的部署方式而是建立一个稳定、简单、便于后续开发的本地或测试环境。2.1 核心组件选择与关系梳理在开始安装前最后明确一下我们技术栈的核心和边界智能体/应用核心我们将使用DeepSeek-V3或GPT-4o这类具备强推理和长文本能力的大模型作为“大脑”。Harness本身不提供模型它是一个调度员。工作流编排器Harness。你可以把它想象成AI时代的“Apache Airflow”但更轻量、更面向AI智能体流程。它通过一个图形化界面或代码来定义和运行包含多个LLM调用、工具调用、条件分支的复杂流程。观测评估平台Langfuse。它是一个开源的LLM应用观测平台。当Harness中的流程调用LLM时Langfuse SDK会自动捕获这次调用的一切细节并存入其数据库供你查询、分析和评分。向量数据库/工具根据财务分析需求你可能需要检索公司历史数据或行业知识。这属于“工具”层可以由Harness调用比如通过Chroma、Weaviate或直接调用相关API。它们的关系如下图所示这是一个逻辑示意图[用户请求] - [Harness 工作流] - [调用LLM] - [Langfuse 记录] ^ | | | v v --[可能调用工具/数据库] [存储记录用于评估和调试]2.2 分步安装与配置指南我们采用最清晰的Docker Compose方式部署这能保证环境隔离和依赖清晰。第一步部署Langfuse观测平台先行Langfuse是相对独立的后台服务我们先把它跑起来。创建一个项目目录例如financial-agent-platform。在该目录下创建docker-compose.langfuse.yml文件。version: 3.8 services: langfuse: image: langfuse/langfuse:latest ports: - 3000:3000 # Langfuse前端界面 environment: - DATABASE_URLpostgresql://postgres:langfusedb:5432/langfuse - NEXTAUTH_SECRETyour-secret-key-change-this # 请务必修改 - NEXTAUTH_URLhttp://localhost:3000 - SALTyour-salt-change-this # 请务必修改 depends_on: db: condition: service_healthy healthcheck: test: [CMD, curl, -f, http://localhost:3000/api/health] interval: 30s timeout: 10s retries: 3 db: image: postgres:15-alpine environment: - POSTGRES_USERpostgres - POSTGRES_PASSWORDlangfuse - POSTGRES_DBlangfuse volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 10s timeout: 5s retries: 5 volumes: postgres_data:在终端中运行docker-compose -f docker-compose.langfuse.yml up -d访问http://localhost:3000使用默认账号 (adminexample.com/password) 登录并立即在设置中修改密码。你会在界面上看到你的PUBLIC_KEY和SECRET_KEY记下来后面Harness会用。第二步配置Harness并连接LangfuseHarness的安装方式多样我们选择其提供的CLI工具进行本地开发部署这是目前最灵活的方式。确保你的系统已安装Python3.9和Node.js18。通过pip安装Harness CLIpip install harness-dev创建一个新的Harness项目harness init financial-agent进入项目目录cd financial-agent编辑Harness的配置文件通常是harness.yml或.env文件添加Langfuse的配置信息将上一步获取的密钥填入# 示例配置位置具体可能因版本略有不同 integrations: langfuse: public_key: your_langfuse_public_key secret_key: your_langfuse_secret_key host: http://localhost:3000 # Langfuse服务地址启动Harness开发服务器harness dev访问http://localhost:8000即可看到Harness的图形化编排界面。至此你的基础架构已经就位一个工作流编排器Harness和一个观测平台Langfuse已经联通。接下来才是真正构建智能体的部分。关键注意环境变量如密钥切勿提交到代码仓库。务必使用.env文件管理并将其加入.gitignore。3. 构建核心设计一个可观测的财务分析智能体工作流现在我们有了舞台和监控系统该演员智能体上场了。在Harness中构建工作流不同于直接写Python脚本它要求你以“节点”和“连线”的思维来设计任务。这恰恰是工程化的关键——强制你进行模块化思考。3.1 拆解财务分析任务为标准化节点一次完整的财务报告分析可以拆解为以下节点每个节点在Harness中可能对应一个“工具”或一个“LLM调用”输入节点接收用户上传的PDF年报文件。文档解析节点使用像Unstructured、PyPDF2或pdfplumber这样的库将PDF转换为纯文本。这一步可能需要处理表格和格式。文本预处理与分块节点年报很长需要按章节如“管理层讨论与分析”、“财务报表附注”进行分割以适应模型的上下文窗口。核心分析节点LLM调用这是重头戏。我们将配置一个LLM节点连接DeepSeek或GPT并编写一个结构化的提示词Prompt要求模型根据指定章节的文本提取关键财务指标如营收、净利润、毛利率并进行初步解读。关键动作在这个节点的配置中确保勾选了“启用追踪”或类似选项并指向我们配置好的Langfuse。这样每次调用都会被记录。数据汇总与格式化节点将多个章节的分析结果可能是JSON格式汇总整理成一份统一的报告。输出节点将最终报告以Markdown或HTML格式返回给用户。在Harness的UI中你可以通过拖拽的方式创建这些节点并用箭头连接它们定义执行顺序。对于“核心分析节点”你需要编写Prompt。3.2 编写可评估的Prompt与启用追踪Prompt的质量直接决定分析效果。工程化的思维要求我们写的Prompt不仅是“有效”的更是“可评估”和“可迭代”的。一个“工程化”的Prompt示例你是一名专业的财务分析师。请分析以下上市公司年报的「{section_name}」章节内容。 **你的任务** 1. 提取以下关键财务数据如果提及 - 营业收入Revenue - 净利润Net Profit - 毛利率Gross Margin - 研发费用RD Expenses - 经营活动现金流Cash Flow from Operations 2. 对提取的每一项数据给出其同比变化百分比如果上下文提供去年数据。 3. 用一句话总结该章节透露出的核心财务信号积极、消极或中性。 **输出格式要求** 请严格按照以下JSON格式输出不要包含任何其他解释性文字 { “extracted_data”: [ {“metric”: “营业收入”, “value”: “...”, “yoy_change”: “...”}, ... ], “summary_signal”: “...” } **章节内容** {chapter_text}这个Prompt的“工程化”之处在于角色清晰定义了AI的职能边界。任务结构化列出了明确、离散的子任务。输出格式化强制要求JSON输出这极其重要。结构化的输出让后续的自动化评估成为可能例如可以写一个规则检查JSON字段是否完整。变量化{section_name}和{chapter_text}是变量由上游节点注入使得Prompt可复用。在Harness中配置这个LLM节点时最关键的一步是启用Langfuse集成。通常这体现为一个配置开关或一个集成选项。启用后每一次这个节点的执行其完整的Prompt包含替换后的变量、模型的完整响应、Token使用量、延迟等信息都会自动发送到Langfuse平台。4. 从“能跑通”到“可信赖”建立评估与迭代闭环工作流能跑通只是万里长征第一步。真正的价值来自于持续的评估和迭代。这就是Langfuse大显身手的地方。4.1 在Langfuse中查看追踪记录运行几次你的财务分析工作流后打开Langfuse界面 (http://localhost:3000)。你应该能在“Traces”页面看到一系列记录。每一条Trace代表一次完整的工作流执行即分析一份年报。点开一条Trace你可以看到其详细的树状结构Harness的每个节点尤其是LLM调用都作为一个“Span”被记录下来。点击任何一个LLM调用的Span你能看到Input 当时发送给模型的完整Prompt和消息。Output 模型返回的完整响应。Metadata 使用的模型、Token数、耗时、成本如果配置了。所有中间步骤 如果使用了Chain of Thought或类似技术这些步骤也会被记录。这彻底打破了黑盒。你现在可以精确地知道是哪一次调用、在什么输入下、产生了什么样的输出。当分析结果不如预期时你可以直接定位到问题节点检查是Prompt理解有误还是输入文本质量太差。4.2 创建评估数据集与人工评分观测是为了评估评估是为了优化。准备评估集选取5-10份不同类型的年报不同行业、不同盈利状况。对于每一份年报人工或借助其他可靠工具生成一份你认为“标准”的分析结果。这将成为你的“Ground Truth”。在Langfuse中创建数据集Langfuse支持创建数据集Datasets。你可以将那些标准的分析结果Ground Truth作为“预期输出”录入系统并与对应的Trace关联起来。进行人工评分浏览Langfuse中记录的每一次分析输出与你数据集中的“标准答案”对比。Langfuse允许你直接在任何Trace或Span上打标签Tag和评分Score。例如你可以定义一个“分析准确性”的评分项范围1-5分然后为每一次运行打分。分析评分数据Langfuse的Dashboard可以让你可视化所有打分的分布。你可以快速发现哪些类型的年报或哪个分析节点得分普遍较低从而定位改进方向。4.3 基于数据驱动Prompt迭代现在你有了数据和反馈。假设你发现对于“制造业”公司的年报毛利率分析经常出错评分低。在Langfuse中筛选利用过滤功能找出所有分析制造业年报的Trace。对比分析逐一查看这些低分Trace的输入和输出。你可能会发现制造业的财报中“毛利率”的计算口径或表述方式与科技公司不同导致模型提取错误。假设与修改基于这个发现你可以修改Prompt在指令中增加针对制造业毛利率计算的特别说明或者增加一个例子Few-shot。A/B测试在Harness中你可以复制一份工作流只修改其中的Prompt节点创建一个新版本Version B。然后用同样的制造业年报数据集分别运行两个版本的工作流。评估结果在Langfuse中两个版本的Trace会被自动记录。你可以通过对比它们在同一份年报上的输出和评分客观地判断新Prompt是否有效。至此你建立了一个完整的“构建-观测-评估-迭代”闭环。这个闭环是AI工程化的核心。它让你从依赖直觉和随机尝试转向依赖数据和系统性实验。5. 走向生产企业级考量与进阶优化当一个智能体在可控环境下表现稳定后就可以考虑将其推向更正式的生产环境。这一步需要考虑更多工程和运维问题。5.1 性能、安全与成本监控性能监控通过Langfuse你已经拥有了每次调用的延迟数据。可以设置警报当P95延迟超过某个阈值时触发告警。Harness本身也可能提供工作流整体执行时间的监控。安全与合规财务数据敏感。确保你的Harness和Langfuse部署在安全的网络环境中启用HTTPS严格管理访问权限。考虑对输入/输出日志进行脱敏处理Langfuse支持数据脱敏策略。成本控制Langfuse可以记录每次调用的Token使用量。如果你配置了模型单价它还能估算每次调用的成本。这对于预测月度API开销和优化提示词以减少Token消耗至关重要。5.2 工作流版本管理与CI/CDHarness通常支持工作流的版本控制。这意味着版本化每次对Prompt或工作流结构的修改都可以保存为一个新版本。回滚如果新版本上线后出现问题可以快速回滚到稳定版本。与代码仓库集成可以将Harness的工作流定义文件通常是YAML或JSON纳入Git管理实现基础设施即代码IaC。结合CI/CD管道可以实现自动化测试和部署。5.3 扩展性设计多模型路由与降级可以在Harness中设计决策节点。例如首先尝试调用性能最好但成本较高的GPT-4如果超时或失败则自动降级调用DeepSeek-V3或Claude Haiku。Langfuse会记录每次实际调用的模型便于后续分析性价比。异步与批处理对于大规模批量分析任务需要将Harness工作流设计为异步执行并通过队列管理任务。避免同步HTTP请求超时。自定义工具集成财务分析可能需要接入外部数据源如Wind、Bloomberg的API或内部数据库。Harness允许你封装这些调用为自定义“工具”节点无缝集成到工作流中。5.4 构建评估体系与报告最终你需要向团队或管理层证明这个智能体的价值。Langfuse的数据可以帮你生成评估报告准确性报告展示智能体在不同行业、不同报告类型上的平均得分及趋势。成本效率报告展示每次分析的平均成本和耗时并与人工分析进行对比。稳定性报告展示工作流执行的成功率、失败原因分布。这些报告是将一个实验性AI项目转化为一个受信任的企业级工具的关键。回过头看这个基于Harness和Langfuse的财务分析智能体项目其核心贡献不在于实现了多么复杂的财务模型而是演示了一条清晰的AI工程化落地路径从模块化的工作流设计到全链路的可观测性再到数据驱动的评估与迭代。它把原本隐藏在脚本里的“魔法”变成了一个透明、可度量、可持续优化的工程系统。对于想在企业内推进AI应用的团队来说最大的障碍往往不是模型能力而是缺乏这样一套“从实验到生产”的支撑体系。这个项目提供了一个切实可行的起点。你可以从财务分析这个具体场景入手跑通整个流程理解每个环节的价值。之后无论是将其应用于法律合同审查、客服对话总结还是市场报告生成这套方法论和工具链都是相通的。真正的AI工程化始于第一次把“黑盒”打开并决定持续地观察它、测量它、改进它。