如果你正在开发基于大语言模型LLM的生产级AI应用是否遇到过这样的困境精心设计的提示词Prompt散落在各个代码文件里改一处功能需要翻遍整个项目。模型输出时好时坏缺乏客观的评估标准只能靠人工“感觉”来判断质量。线上应用出了问题只知道最终结果不对却无法追溯是哪个提示词、哪次模型调用、哪个中间环节导致了偏差。这不仅仅是工程管理问题更是AI应用从“玩具Demo”走向“生产级服务”必须跨越的鸿沟。传统的软件监控Observability工具如日志、指标和链路追踪在面对非确定性的LLM时常常力不从心。我们需要一套全新的、面向AI原生的工作流和工具链。今天要深入探讨的正是解决这些核心痛点的关键理念与实践框架Prompt注册中心Prompt Registry、LLM评估LLM Evals与AI可观测性AI Observability。它们并非某个单一工具而是一套相辅相成的工程范式。本文将为你彻底拆解这三者的内涵、价值并提供一套可落地的、结合开源工具的实现方案。1. 这篇文章真正要解决的问题这篇文章要解决的不是如何调用一次API而是如何系统化、工程化地构建和维护一个可靠、可维护、可观测的AI应用。很多开发者误以为AI应用开发就是“设计Prompt 调用API”。但在生产环境中这种模式会迅速导致技术债堆积提示词管理失控没有版本、没有复用、没有AB测试迭代成本极高。质量评估黑盒无法量化模型表现回归测试困难优化方向模糊。排障如同破案当用户反馈“答案不对”时你需要从海量日志中手动还原调用链、输入输出和中间状态效率低下。因此本文的核心判断是将Prompt视为一等公民进行管理并建立贯穿开发、测试、部署、监控全链路的评估与观测体系是AI工程化成熟度的分水岭。无论你是使用 LangChain、LlamaIndex 等框架还是直接调用底层API无论你的应用是问答机器人、代码助手还是智能客服这套方法论都具有普适性。读完本文你将能理解Prompt Registry、LLM Evals、Observability的核心概念与联系。掌握如何利用现有开源工具如PromptFlow、LangSmith、Trulens等搭建最小可行工作流。获得一套可直接用于项目的代码示例、配置方法和最佳实践清单。2. 基础概念与核心原理在深入实操前必须厘清三个核心概念及其内在联系。2.1 Prompt Registry不只是存储更是生命周期管理通俗解释你可以把它理解为AI应用的“配置中心”或“物料库”。但它管理的不是普通的配置项而是直接决定AI行为与能力的提示词。核心功能版本控制像Git管理代码一样管理Prompt的变更历史支持回滚、对比。参数化与模板化将Prompt抽象为模板动态注入变量如用户问题、上下文片段。环境隔离为开发、测试、生产环境配置不同的Prompt版本或参数。集中化存储与分发所有服务从统一的中心获取Prompt确保一致性。解决的问题告别硬编码的Prompt实现提示词的复用、安全迭代和高效协作。2.2 LLM Evals量化评估取代主观臆断通俗解释一套用于自动化评估LLM输出质量的工具和方法。它回答的是“这个模型回答得好不好”以及“比之前好了多少”评估维度忠实度/事实性答案是否与提供的上下文一致是否包含事实错误相关性答案是否切题完整性答案是否涵盖了问题的所有方面有害性/安全性答案是否包含偏见、歧视或不安全内容代码正确性对于代码生成任务生成的代码能否通过单元测试自定义指标根据业务需求定义如“销售话术的友好度”、“客服回复的解决率”。核心原理通常通过另一个LLM作为裁判Judge LLM或一套规则引擎如正则表达式、代码执行来对输出进行评分。解决的问题为模型优化和迭代提供客观、可量化的依据支撑自动化测试和持续集成。2.3 Observability for AI穿透非确定性的黑盒通俗解释传统可观测性关注的是“系统是否在正常运行”而AI可观测性更关注“系统为什么会产生这个输出”。它需要追踪一次AI调用中所有影响结果的要素。核心数据维度提示词与参数本次调用具体使用了哪个版本的Prompt输入变量是什么模型与配置调用了哪个模型温度temperature、top_p等参数如何设置完整输入/输出不仅是最终问答还包括多轮对话历史、检索到的上下文RAG场景。中间步骤与成本在链式Chain或智能体Agent调用中每一步的输入输出、耗时、Token消耗。评估结果将本次调用的输出用Evals进行评估并将评分关联存储。解决的问题当线上出现bad case时能快速复现、定位根因是Prompt问题上下文检索问题还是模型本身问题并基于数据驱动优化。2.4 三者关系一个闭环工作流这三者构成了一个完整的AI应用质量保障闭环开发阶段在Prompt Registry中编写和版本化管理Prompt。测试/评估阶段使用LLM Evals对新的Prompt或模型进行自动化评估确保质量达标。部署阶段将通过评估的Prompt版本发布到生产环境。监控阶段通过Observability工具收集生产环境的所有调用数据。分析与迭代基于监控数据发现bad case分析原因回到第1步优化Prompt或流程并用Evals验证改进效果。3. 环境准备与前置条件我们将以一个基于RAG检索增强生成的智能问答应用为场景演示如何整合这三部分。示例将主要使用Python和流行的开源框架。基础环境要求操作系统Linux / macOS / Windows (WSL2推荐)Python版本3.9 或以上包管理工具pip 或 poetry核心工具选型 为了覆盖全链路我们选择以下一组互补的开源/云服务工具进行演示你可以根据实际情况替换Prompt管理/编排PromptFlow(微软开源)。它内置了开发、测试、评估和部署的能力非常适合作为一体化演示框架。评估框架RAGAS(开源)。专注于评估RAG管道质量的库评估维度全面。可观测性平台LangSmith(LangChain旗下)。提供强大的Trace追踪、数据集管理和评估功能与LangChain生态无缝集成。注LangSmith有云服务和自托管选项本文以云服务为例自部署流程类似安装核心依赖 创建一个新的Python虚拟环境并安装以下包# 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 安装 PromptFlow 核心包及AI连接器 pip install promptflow promptflow-tools openai # 安装 RAGAS 用于评估 pip install ragas # 安装 LangChain 和 LangSmith SDK (用于可观测性) pip install langchain langsmith # 可选安装常用的工具包如向量数据库客户端 pip install chromadb sentence-transformers获取API密钥OpenAI API Key用于访问GPT模型。从 OpenAI平台 获取。LangSmith API Key用于将追踪数据发送到LangSmith。从 LangSmith网站 注册并获取。将密钥设置为环境变量这是安全且通用的做法# 在终端中设置临时 export OPENAI_API_KEYsk-你的openai-key export LANGCHAIN_API_KEYls_你的langsmith-key export LANGCHAIN_TRACING_V2true export LANGCHAIN_PROJECTMy-AI-Observability-Project # 指定项目名或者在Python代码中初始化import os os.environ[OPENAI_API_KEY] sk-你的openai-key os.environ[LANGCHAIN_API_KEY] ls_你的langsmith-key os.environ[LANGCHAIN_TRACING_V2] true os.environ[LANGCHAIN_PROJECT] My-AI-Observability-Project4. 核心流程拆解构建可观测的RAG应用我们将分步构建一个具备完整可观测性的简单RAG应用。4.1 第一步使用PromptFlow定义与管理PromptPromptFlow使用YAML文件来定义“流”Flow其中就包含了Prompt模板。这本身就是一种Prompt Registry的实践。创建Flow目录结构my_rag_flow/ ├── flow.dag.yaml # 流的主定义文件 ├── prompt.jinja2 # 提示词模板文件 ├── chat.py # 自定义Python工具节点例如检索 └── connections.yaml # 连接配置如API密钥定义提示词模板 (prompt.jinja2) 我们将Prompt从代码中分离出来并进行参数化。{# prompt.jinja2 #} 你是一个专业的助手请严格根据以下上下文回答问题。 如果上下文不包含相关信息请直接说“根据提供的资料我无法回答这个问题”不要编造信息。 上下文 {{ context }} 问题{{ question }} 请用中文回答这个模板定义了两个输入变量context和question。版本变更只需修改此文件。定义流逻辑 (flow.dag.yaml) 这个文件描述了从输入到输出的执行图。# flow.dag.yaml id: basic_rag_flow name: Basic RAG Flow nodes: - name: retrieve type: python source: type: code path: chat.py inputs: query: ${inputs.question} outputs: context: ${retrieve.context} - name: generate_answer type: llm source: type: prompt path: prompt.jinja2 inputs: question: ${inputs.question} context: ${retrieve.context} connection: open_ai_connection # 引用配置的连接 outputs: answer: ${generate_answer.content} inputs: question: type: string outputs: answer: ${generate_answer.answer}实现检索节点 (chat.py) 这是一个简化的检索模拟实际中会连接向量数据库。# chat.py import json # 模拟一个简单的文档库 FAKE_KNOWLEDGE_BASE { 什么是Python: Python是一种高级、解释型的通用编程语言以其清晰的语法和代码可读性而闻名。, 如何学习机器学习: 学习机器学习需要掌握数学基础线性代数、概率论、编程技能如Python并学习经典算法和框架。 } def retrieve(query: str) - dict: 模拟检索过程返回上下文。 # 实际项目中这里会是向量相似度搜索 context FAKE_KNOWLEDGE_BASE.get(query, 未找到相关信息。) return {context: context}配置连接 (connections.yaml) 将敏感的API密钥配置在独立文件中。# connections.yaml open_ai_connection: type: open_ai api_key: ${env:OPENAI_API_KEY} # 从环境变量读取 api_base: https://api.openai.com/v1至此我们完成了Prompt的模板化、版本化通过文件管理和参数化。flow.dag.yaml清晰地定义了应用的工作流。4.2 第二步使用RAGAS进行自动化评估现在我们需要评估这个RAG流的效果。我们创建一组测试用例问题-标准答案对并使用RAGAS进行评估。创建评估数据集# eval_dataset.py import pandas as pd # 模拟一个评估数据集 eval_data [ { question: 什么是Python, ground_truth: Python是一种广泛使用的高级、解释型编程语言强调代码可读性。, contexts: [[Python是一种高级、解释型的通用编程语言以其清晰的语法和代码可读性而闻名。]] }, { question: 如何学习机器学习, ground_truth: 需要学习数学、编程并理解机器学习算法。, contexts: [[学习机器学习需要掌握数学基础线性代数、概率论、编程技能如Python并学习经典算法和框架。]] }, { question: 什么是黑洞, # 知识库中没有的问题 ground_truth: 根据资料无法回答。, contexts: [[未找到相关信息。]] } ] df pd.DataFrame(eval_data) df.to_json(eval_dataset.jsonl, orientrecords, linesTrue) print(评估数据集已保存至 eval_dataset.jsonl)运行Flow并收集输出 首先我们需要用我们的Flow处理评估集中的问题得到模型的“实际答案”。# run_flow_for_eval.py import promptflow import pandas as pd import json # 加载Flow pf promptflow.PFClient() flow_path ./my_rag_flow # 加载评估数据集 df pd.read_json(eval_dataset.jsonl, linesTrue) results [] for _, row in df.iterrows(): # 准备输入 inputs {question: row[question]} # 运行Flow flow_result pf.test(flowflow_path, inputsinputs) # 收集结果 results.append({ question: row[question], answer: flow_result[answer], # 模型实际输出 contexts: row[contexts], ground_truth: row[ground_truth] }) # 保存运行结果供RAGAS评估使用 with open(flow_outputs_for_eval.json, w) as f: json.dump(results, f, indent2, ensure_asciiFalse) print(Flow运行结果已保存至 flow_outputs_for_eval.json)使用RAGAS进行评估# run_ragas_eval.py from ragas import evaluate from ragas.metrics import faithfulness, answer_relevancy, context_recall, context_precision from datasets import Dataset import json # 加载Flow的运行结果 with open(flow_outputs_for_eval.json, r) as f: data json.load(f) # 转换为RAGAS需要的Dataset格式 # RAGAS期望的列名是固定的question, answer, contexts, ground_truth eval_dataset Dataset.from_list(data) # 选择要评估的指标 metrics [ faithfulness, # 答案是否基于上下文 answer_relevancy, # 答案是否与问题相关 context_recall, # 检索到的上下文是否包含了标准答案所需的信息 # context_precision, # 检索到的上下文是否精确本例上下文是模拟的暂不评估 ] # 执行评估 result evaluate( dataseteval_dataset, metricsmetrics, ) # 查看评估结果 print(RAGAS 评估结果:) print(result) # 也可以转换为Pandas DataFrame进行详细分析 result_df result.to_pandas() print(\n详细评分表:) print(result_df[[question, faithfulness, answer_relevancy, context_recall]])运行此脚本你会得到每个测试用例在各个指标上的分数通常0-1分以及平均分。这为Prompt和检索器的优化提供了明确方向。4.3 第三步集成LangSmith实现可观测性我们需要在应用运行时将每一次调用的详细信息Trace发送到LangSmith。在Flow中集成LangChain Callback PromptFlow支持与LangChain集成。我们需要修改Flow的配置使其在调用LLM时使用LangChain的Callback。首先安装集成包pip install promptflow[langchain]然后修改flow.dag.yaml中的LLM节点使用LangChain的ChatOpenAI组件并自动启用追踪# flow.dag.yaml (修改generate_answer节点) - name: generate_answer type: python # 改为python类型以便使用LangChain source: type: code path: llm_node_with_langsmith.py # 指向新的实现文件 inputs: question: ${inputs.question} context: ${retrieve.context} outputs: answer: ${generate_answer.result}创建集成了LangSmith的LLM节点# llm_node_with_langsmith.py from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser import os # 环境变量中已设置 LANGCHAIN_API_KEY 和 LANGCHAIN_TRACING_V2 # LangSmith会自动捕获所有通过LangChain发起的调用 def run_llm(question: str, context: str) - str: # 1. 构建Prompt模板与之前的Jinja2模板对应 prompt_template ChatPromptTemplate.from_messages([ (system, 你是一个专业的助手请严格根据以下上下文回答问题。\n如果上下文不包含相关信息请直接说“根据提供的资料我无法回答这个问题”不要编造信息。\n\n上下文\n{context}), (human, {question}\n\n请用中文回答) ]) # 2. 选择模型 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 3. 构建链 chain prompt_template | llm | StrOutputParser() # 4. 执行调用此次调用会被自动记录到LangSmith result chain.invoke({context: context, question: question}) return {result: result}运行并查看追踪结果 现在当你运行这个修改后的Flow时每次调用都会在LangSmith平台上生成一个详细的Trace。前往 LangSmith网站 。在左侧菜单选择“Traces”。你会看到按时间排列的所有调用记录。点击任意一条Trace你可以看到完整的输入和输出。使用的Prompt模板和变量。模型类型和参数。Token消耗和延迟。调用链中每一步的输入输出如果使用了更复杂的Chain。5. 完整示例端到端工作流整合我们将上述三步整合到一个脚本中模拟从开发到评估再到监控的完整流程。# full_workflow_demo.py 一个完整的演示运行RAG Flow - 自动评估 - 记录追踪到LangSmith。 import os import json import pandas as pd from promptflow import PFClient from ragas import evaluate from ragas.metrics import faithfulness, answer_relevancy from datasets import Dataset # 1. 配置环境 os.environ[OPENAI_API_KEY] sk-你的openai-key os.environ[LANGCHAIN_API_KEY] ls_你的langsmith-key os.environ[LANGCHAIN_TRACING_V2] true os.environ[LANGCHAIN_PROJECT] Full-Workflow-Demo # 2. 定义评估数据集 print(步骤1: 准备评估数据集...) eval_data [ { question: Python的主要特点是什么, ground_truth: 代码可读性好语法清晰是解释型语言。, contexts: [[Python是一种高级、解释型的通用编程语言以其清晰的语法和代码可读性而闻名。]] }, ] eval_df pd.DataFrame(eval_data) eval_df.to_json(workflow_eval_data.jsonl, orientrecords, linesTrue) # 3. 初始化PromptFlow客户端 print(\n步骤2: 初始化并运行PromptFlow...) pf PFClient() flow_path ./my_rag_flow # 假设这是你的Flow目录 # 4. 运行Flow处理评估问题并收集结果此过程会被LangSmith记录 results_for_ragas [] for _, row in eval_df.iterrows(): inputs {question: row[question]} try: # 运行Flow。注意我们使用了集成了LangSmith的Flow版本。 flow_result pf.test(flowflow_path, inputsinputs) actual_answer flow_result.get(answer, No answer generated.) print(f问题: {row[question]}) print(f答案: {actual_answer[:100]}...) # 打印前100字符 results_for_ragas.append({ question: row[question], answer: actual_answer, contexts: row[contexts], ground_truth: row[ground_truth] }) except Exception as e: print(f运行Flow时出错: {e}) results_for_ragas.append({ question: row[question], answer: , contexts: row[contexts], ground_truth: row[ground_truth] }) # 5. 使用RAGAS进行评估 print(\n步骤3: 使用RAGAS进行自动化评估...) if results_for_ragas: ragas_dataset Dataset.from_list(results_for_ragas) metrics_to_use [faithfulness, answer_relevancy] evaluation_result evaluate(datasetragas_dataset, metricsmetrics_to_use) print(评估分数:) print(evaluation_result) # 可以将评估结果也关联到LangSmith的Trace中高级用法需通过LangSmith SDK else: print(没有有效结果用于评估。) # 6. 总结与指引 print(\n *50) print(工作流执行完成) print(1. Prompt管理通过PromptFlow的YAML和Jinja2文件实现。) print(2. 评估结果见上方RAGAS输出量化了答案的忠实度和相关性。) print(3. 可观测性请访问 https://smith.langchain.com/ 查看本次运行的详细Trace。) print(*50)运行这个脚本你将一次性体验到Prompt的集中化调用通过Flow。自动化评估通过RAGAS。完整的调用追踪在LangSmith平台查看。6. 运行结果与效果验证6.1 预期输出运行full_workflow_demo.py后你将在控制台看到类似输出步骤1: 准备评估数据集... 步骤2: 初始化并运行PromptFlow... 问题: Python的主要特点是什么 答案: Python的主要特点是语法清晰、代码可读性强它是一种高级的解释型编程语言... 步骤3: 使用RAGAS进行自动化评估... 评估分数: {faithfulness: 0.95, answer_relevancy: 0.92} 工作流执行完成 1. Prompt管理通过PromptFlow的YAML和Jinja2文件实现。 2. 评估结果见上方RAGAS输出量化了答案的忠实度和相关性。 3. 可观测性请访问 https://smith.langchain.com/ 查看本次运行的详细Trace。 6.2 验证方式验证Prompt管理检查my_rag_flow/prompt.jinja2文件。修改其中的系统指令重新运行脚本观察输出是否相应改变。这验证了Prompt与代码的解耦。验证评估结果RAGAS输出的分数应在0到1之间。你可以故意修改llm_node_with_langsmith.py中的Prompt去掉“根据上下文”的限制再次运行观察faithfulness分数是否下降。这验证了评估的有效性。验证可观测性登录LangSmith控制台。在“Traces”页面你应该能看到名为“Full-Workflow-Demo”的项目下有一条新的Trace。点击进入该Trace你应该能清晰看到Inputs:{“context”: “…”, “question”: “Python的主要特点是什么”}Output: 模型生成的完整答案。模型信息gpt-3.5-turbo,temperature0。Token使用情况。完整的Prompt模板。如果以上三点都成功说明你已成功搭建了一个具备初步Prompt管理、自动化评估和全链路观测能力的AI应用原型。7. 常见问题与排查思路问题现象可能原因排查方式解决方案PromptFlow运行失败提示连接错误1. OpenAI API Key未设置或错误。2.connections.yaml配置有误。1. 检查echo $OPENAI_API_KEY。2. 检查connections.yaml文件格式和路径。1. 正确设置环境变量。2. 确保YAML缩进正确使用pf configure测试连接。RAGAS评估时报错或分数为NaN1. 评估数据格式不正确。2. 答案或上下文为空字符串。3. 调用的评估模型默认可能是GPT无权限。1. 检查eval_dataset的列名是否为question,answer,contexts,ground_truth。2. 打印中间数据确认无空值。3. 检查是否设置了OPENAI_API_KEY。1. 严格按照RAGAS文档准备数据。2. 在评估前进行数据清洗。3. 确保有可用的LLM API Key供RAGAS调用作为Judge LLM。LangSmith控制台看不到Trace1.LANGCHAIN_API_KEY环境变量未设置或错误。2.LANGCHAIN_TRACING_V2未设置为true。3. 代码未通过LangChain组件调用LLM。1. 确认环境变量已导出并在Python进程中生效。2. 检查代码中是否直接用了openai库而非langchain。1. 在运行脚本的终端和IDE中确认环境变量。2. 确保所有LLM调用都通过langchain_openai.ChatOpenAI等LangChain组件进行。评估分数普遍偏低1. Prompt设计不佳。2. 检索到的上下文质量差。3. 评估指标或标准不匹配业务。1. 在LangSmith中分析bad case的输入输出。2. 检查检索逻辑看返回的上下文是否相关。3. 审视RAGAS的评估标准是否合理。1. 迭代优化Prompt。2. 优化检索器如嵌入模型、分块策略。3. 为RAGAS实现自定义评估指标。生产环境部署复杂将PromptFlow流、评估脚本、LangSmith集成到现有服务中需要改造。评估现有架构是单体应用还是微服务。1.轻量级集成将PromptFlow流打包为Docker服务通过HTTP调用。2.架构升级考虑将Prompt Registry如PromptFlow服务化、评估服务、可观测性数据收集作为独立中间件。8. 最佳实践与工程建议将这套方法论落地到真实生产环境需要更周密的考虑。8.1 Prompt Registry 进阶实践GitOps for Prompt将包含Prompt模板的Flow目录纳入Git仓库管理。任何Prompt的修改都通过Pull Request进行并触发CI/CD流水线自动运行评估测试。AB测试与灰度发布在注册中心维护多个版本的Prompt。通过路由策略如根据用户ID哈希将流量分发到不同版本在LangSmith中对比不同版本的核心指标如回答满意度、任务完成率。敏感信息检测在Prompt注册和发布流程中加入自动化扫描防止密钥、内部IP等敏感信息被写入Prompt。8.2 LLM Evals 工程化构建高质量的评估数据集这是评估有效性的基石。数据集应覆盖核心用例、边界用例和常见的对抗性用例。可以借助LLM如GPT-4来批量生成和筛选测试用例。分层评估体系单元测试级针对单个Prompt或组件的快速评估如格式检查、关键词检查。集成测试级针对完整工作流的评估如RAGAS评估。人工评估定期抽样进行更复杂、更主观的人工评分并用于校准自动化评估指标。将评估集成到CI/CD在代码合并或Prompt更新时自动运行评估套件设定质量阈值如faithfulness平均分0.9不达标则阻止发布。8.3 Observability 生产级部署定义关键指标与告警业务指标任务完成率、用户满意度可通过后续反馈或代理指标衡量。质量指标自动化评估分数的趋势如每周平均faithfulness分数。性能与成本指标平均响应延迟、Token消耗分布、错误率。设置告警当关键指标如错误率、平均延迟超过阈值时触发告警。采样与存储策略生产环境调用量巨大全量追踪数据成本高昂。需要制定采样策略如1%全量采样对错误请求、新用户或新Prompt版本提高采样率。并规划数据的长期存储与归档。根因分析工作台利用LangSmith等平台的筛选和聚合功能快速定位问题。例如筛选出所有“faithfulness评分低于0.5”的Trace分析其共同特征是否源于某类特定问题或某个特定的上下文。8.4 安全与合规数据脱敏在将输入输出发送到可观测性平台前对用户个人信息、密钥等敏感数据进行脱敏处理。审计日志记录谁在何时修改了哪个Prompt以及修改内容满足合规要求。权限控制对Prompt Registry、评估数据集、可观测性数据设置严格的访问权限如开发人员可读只有负责人可写。从“写死”的Prompt到可管理的Prompt资产从“拍脑袋”评估到数据驱动的自动化测试从“盲人摸象”式的排障到全链路可观测——这套组合拳是构建稳健、可信、可持续迭代的生产级AI应用的基石。它带来的不仅是开发体验的提升更是团队协作模式和质量保障体系的升级。你可以从本文提供的本地化、开源工具栈方案开始逐步实践。随着应用复杂度和团队规模的增长再考虑引入更企业级的商业化产品。核心在于尽早建立起“管理-评估-观测”的思维闭环这将帮助你在AI工程化的道路上走得更稳、更远。