Promptflow：微软提示词工作流管理

为什么需要 Promptflow：提示词迭代不可控 → 全链路可评估可部署

传统 LLM 应用开发的主要问题不是「调一个 API」，而是「改一轮 prompt」。一次提示词调整会连锁影响下游输出，团队靠人工逐条看对话结果判断好坏，改几轮就说不清哪一版更好；代码里 model 名、api_key、prompt 模板混在一起，本地跑通和线上部署是两套东西，上线后一次调用到底经过哪些节点、耗在哪里，只能靠猜。

Promptflow 把这些问题压进同一条链路：prompt 模板、工具节点、输入输出定义全部沉淀到一个 flow 目录，用 YAML 描述 DAG、用 Python/Jinja2 写节点逻辑。一次 pf run create 就能在相同测试集上批量跑多个候选版本并对比结果；pf flow serve 把同一个流变成 HTTP 服务；VS Code 里调试的流目录，原样部署到 Azure AI Foundry。从原型到生产，用的是同一份定义。

它与同类工具的气质差异在于「可校验的资产化」：节点引用、输入输出 schema、连接对象全部显式声明，flow 定义可被校验、可批量评估、可审计，这使它更适合要上线、要评测、要对齐规范的工程团队，而不是「快速写段脚本调模型」的原型场景。

安装与环境配置：3 步就绪

步骤一：创建独立虚拟环境并安装核心包。要求 Python 3.9+。promptflow 是运行时与 CLI，promptflow-tools 提供 LLM、Embedding、Serp 等内置节点，两个都要装。

步骤二：验证 CLI。输出版本号即安装成功。VS Code 用户可额外安装官方「Prompt flow」扩展，在扩展中图形化编辑与调试 flow.dag.yaml——扩展只是入口，核心资产仍是目录下的 YAML 与 Python 文件。

步骤三：创建连接（使用 LLM 节点前的必做项）。连接（Connection）统一封装 API Key 与端点，flow 里只写连接名，密钥不进代码仓库。新建 openai.yaml 后执行创建命令：

python -m venv .venvsource .venv/bin/activate      # Windows 用 .venv\Scripts\activatepip install promptflow promptflow-tools

pf versionpf --help

$schema: https://azuremlschemas.azureedge.net/promptflow/latest/OpenAIConnection.schema.jsontype: open_ainame: open_ai_connectionapi_key: "<你的API Key>"

pf connection create --file openai.yamlpf connection list      # 确认连接已存在

快速上手：10 分钟跑通第一个流

思路：用 CLI 初始化一个标准流模板，把默认节点改造成 LLM 节点，校验后单测，再从控制台进入本地 trace 页面查看调用详情。标准流（Standard flow）是最通用的形态：输入 question，经一个节点，输出 answer。

1. 初始化：pf flow init --folder ./myflow --type standard，生成 flow.dag.yaml 与一个 Python 工具文件；随后 pf flow validate --flow ./myflow 校验图结构。

2. 确认连接：执行 pf connection list，若列表为空，按上一节创建 open_ai_connection。

3. 改造为 LLM 节点：将 flow.dag.yaml 替换为下面内容，并在同目录新建 llm.jinja2 模板文件。jinja2 文件即 prompt 模板，{{question}} 在运行时被替换为输入值。

4. 校验并测试：

控制台会打印答案，并输出一个本地 trace 链接（形如 http://localhost:port/）。浏览器打开可查看该次调用的节点耗时、实际发送给模型的 prompt 与返回内容。结果符合预期后，这个目录就是后续部署的同一份产物。

进阶：如需接入自有逻辑，新建 Python 工具节点——文件内用 @tool 装饰函数，DAG 里加 type: python 节点，source.path 指向该文件，输入引用 ${llm.output}，改完重新 validate + test。

inputs:  question:    type: stringoutputs:  answer:    type: string    reference: ${llm.output}nodes:- name: llm  type: llm  source:    type: code    path: llm.jinja2  inputs:    connection: open_ai_connection    model: gpt-4o-mini    temperature: 0.7

System:You are a helpful assistant. User:{{question}}

pf flow validate --flow ./myflowpf flow test --flow ./myflow --inputs question="什么是 Microsoft Azure？"

# my_tool.pyfrom promptflow import tool @tooldef count_chars(text: str) -> int:    """统计输入字符数，供 DAG 中 python 节点调用。"""    return len(text)

核心能力详解：4 大支柱

支柱一·三类流与 DAG 编排。标准流处理单轮输入输出，适合 RAG 与工具调用；聊天流（Chat flow）按规范维护 chat_history 字段，开箱即用多轮对话；评估流（Evaluation flow）接收其他流的一次运行结果，产出合格率、相关性等指标。节点类型覆盖 LLM、Python 与内置工具（Embedding、向量索引、Serp 搜索），节点间用 ${node_name.output} 连接，图结构即 flow.dag.yaml，天然可做代码评审与版本回溯。

支柱二·Tracing 可观测性。1.0 重写的 Tracer 在每次 flow 测试或运行时自动记录各节点输入、输出、耗时与 LLM 调用明细，本地以 trace 链接查看；对非 flow 的任意 Python 程序，可用 from promptflow import start_trace 接入，让脚本里的 LLM 调用同样落进追踪。线上异常时能按 run id 回放一次对话的完整执行路径。

支柱三·批量评估。评估不是「跑一遍看看」，而是用同一份测试集对多个 prompt 版本并行执行。pf run create --flow ./myflow --data eval.jsonl --column-mapping 'question="${data.question}"' 对每条样本跑一次完整流，结果落成 jsonl；再配合一个评估流计算指标，即可量化对比不同版本的好坏，替代人工抽查。

支柱四·连接与环境抽象。Connection 封装 api_key、端点与版本号，flow 只引用连接名，密钥不落代码；团队环境切换只换连接对象。自定义连接（Custom Connection）可塞任意键值供 Python 节点使用，便于接入企业内网服务，实现代码与外部依赖解耦。

生产部署与监控：从上线到运维

方式一·本地服务化。用 pf flow serve 把流启动为 HTTP 服务，端点默认 POST /score，用于集成测试、压测前验证，也是容器化打包的基础。

方式二·Azure AI Foundry 在线端点。把本地 flow 目录注册/上传到工作区（通过 VS Code 扩展的发布入口或 azure-ai-ml SDK），创建在线端点并选择 promptflow-runtime 基础镜像，即可获得带鉴权与自动扩缩容的 REST 端点；部署单元就是本地那份 flow 目录，从源头消除「本地行、线上不行」的环境漂移。离线大文件场景改用批量运行模式。

方式三·离线批处理。定时任务与大规模评估用 pf run create 在本地或云端跑 batch，输出 jsonl 便于审计与追溯，适合每轮发版前的回归测试。

可观测性：生产环境建议把 tracing 接入 Application Insights / Azure Monitor，按流名、节点维度看耗时、token 消耗与错误率；线上端点日志记录每次请求输入输出，可叠加评估集做持续回归。本地开发期，pf flow test / pf run 自动输出的 trace 链接已能覆盖绝大多数问题定位。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>0.x 与 1.x 命令不兼容：1.0 GA 是 breaking change，CLI 参数从 --source 改为 --flow，并新增 pf run / pf trace 子命令，网上存量 0.x 教程照抄会直接报错，动手前先看官方 1.x 文档并核对 pf --help。</li><li>只装 promptflow 找不到内置 LLM 节点：内置工具在 promptflow-tools 包里，两个包必须一起装，否则 flow 校验时报 tool not found。</li><li>连接未建就校验：LLM 节点的 connection 字段必须指向已存在连接，先 pf connection list 确认；API Key 写在连接对象里而不是 YAML 明文，带 key 的 yaml 文件要加进 .gitignore。</li><li>引用语法写错：节点间引用是 ${节点名.输出名}，不是 $() 也不是 {{}}；{{ }} 只出现在 jinja2 模板文件内，混用会导致校验失败且报错信息不直观。</li><li>依赖冲突：promptflow 对 openai SDK、protobuf 等依赖版本较敏感，与 LangChain 等框架共用环境易起冲突，建议为 promptflow 单独建虚拟环境。</li></ul>

pf flow serve --flow ./myflow --port 8080curl -X POST http://localhost:8080/score -H "Content-Type: application/json" -d '{"question": "hello"}'

版本迭代

Promptflow 从 2023 年作为 Azure Machine Learning 的提示词功能公开预览起步，经历 0.x 预览期，于 2024 年 7 月以 1.0.0 GA 完成 CLI 重组与 Tracer 重写；此后以月度小版本迭代为主，重心落在可观测性、稳定性与部署链路完善（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题

参考来源

• webpage官方示例集RAG、Agent、评估等示例流