使用 Parea 观测、测试与微调 InstructorOpenAI 客户端的两行代码接入实战【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本文基于instructor仓库中的 parea.md 展开。Parea 是一个面向 LLM 应用的观测Observability、协作与标注平台本文将以「让 LLM 写出只包含 instructor 官方文档链接的邮件」为例演示如何用两行代码为instructor接入 Parea并深入讲解其自动分组重试 Trace、验证错误统计与 Form Mode 标注微调三大特性同时结合仓库源码解释底层原理。为什么 Parea 特别适合 instructorinstructor通过 Pydantic 模型为 LLM 提供结构化输出并在校验失败时自动重试reask。这种「校验—重试」机制给观测带来了两个痛点一次成功的调用背后可能隐藏着多次失败的重试普通日志很难还原完整链路校验错误发生在 Pydantic 层而非 HTTP 层传统监控无从感知。Parea 针对这两个场景提供了原生支持自动分组重试 Trace因重试产生的一系列 LLM 调用会被自动归并到同一条 Trace 下从根 Trace 可以一次看全输入、输出与中间失败便于定位成本与延迟来源自动追踪验证错误使用instructor时发生的任何校验失败次数及涉及字段都会被自动捕获作为该 Trace 的评分score从而支持在仪表盘中可视化、在表格中筛选表单化标注 UI以填表Form Mode方式替代直接编辑 JSON 对象来标注函数调用/工具使用响应降低非开发者的标注门槛标注数据可导出用于微调。从源码结构看instructor的重试逻辑在 instructor/core/retry.py 中统一封装v2 时代迁移至 instructor/v2/core/retry.py它负责在ValidationError触发时构造 reask prompt 并最多重试max_retries次。这正解释了为什么 Parea 能够把「一次client.messages.create调用」识别为一条包含多次子调用的 Trace——重试发生在instructor的包装层内部Parea 的探针因此能看到完整的子调用序列。准备工作安装与 API Key开始前需要完成两件事注册 Parea 账号并创建 API KeyPAREA_API_KEY安装依赖包pip install -U parea-ai instructor安装完成后把PAREA_API_KEY写入环境变量例如通过export PAREA_API_KEYyour-key或.env文件配合python-dotenv加载。两行代码接入wrap_openai_client 与 from_providerParea 与instructor的集成就两步先让 Parea 包装 OpenAI 客户端再用instructor构建结构化客户端。import os import instructor from dotenv import load_dotenv from openai import OpenAI from parea import Parea # 从 parea 模块导入 Parea load_dotenv() client OpenAI() p Parea(api_keyos.getenv(PAREA_API_KEY)) # 使用原生集成开启追踪 p.wrap_openai_client(client, instructor) client instructor.from_provider(openai/gpt-4o)其中p.wrap_openai_client(client, instructor)是关键它会把探针挂到 OpenAI 客户端上并将该客户端命名为instructor后续所有经此客户端发起的调用包括instructor内部的自动重试都会被归组到名为instructor的 Trace 下。from_provider是仓库中统一客户端工厂的核心入口定义在 instructor/v2/auto_client.py它接受形如provider/model-name的模型字符串例如openai/gpt-4o底层通过 ALIAS_TO_PROVIDER 别名映射找到对应 Provider 实现自动完成patch与模式Mode选择返回一个带结构化输出能力的Instructor或AsyncInstructor客户端。因此这里的client同时具备 OpenAI 的原始能力与 Parea 的追踪能力。实战示例生成只含 instructor 文档链接的邮件我们让模型写一封邮件其中只能包含instructor文档的 URL。首先定义一个 Pydantic 模型并用field_validator在生成结果上做二次校验校验 URL 域名必须是python.useinstructor.com且链接真实可访问HTTP 200 且页面不含 404。from pydantic import BaseModel, Field, field_validator import re import requests class Email(BaseModel): subject: str body: str Field( ..., descriptionEmail body, Should contain links to instructor documentation. , ) field_validator(body) def check_urls(cls, v): urls re.findall(rhttps?://(?:[-\w.]|(?:%[\da-fA-F]{2})), v) errors [] for url in urls: if not url.startswith(https://python.useinstructor.com): errors.append( fURL {url} is not from useinstructor.com, Only include URLs that include use instructor.com. ) response requests.get(url) if response.status_code ! 200: errors.append( fURL {url} returned status code {response.status_code}. Only include valid URLs that exist. ) elif 404 in response.text: errors.append( fURL {url} contained 404 in the body. Only include valid URLs that exist. ) if errors: raise ValueError(\n.join(errors)) return注意这里check_urls返回None而非v属于有意为之只要校验不抛异常就视为通过instructor在重试机制中会把ValidationError及错误信息拼入下一次请求引导模型修正输出。这一「校验失败 → 收集错误 → 重试」的闭环正是 instructor/v2/README.md 中描述的 reask 流程在ValidationError时使用注册表处理器生成 reask prompt并最多重试max_retries次。接下来调用client.messages.create传入response_modelEmail并通过template_inputs注入两个文档链接占位符email client.messages.create( modelgpt-4o, max_tokens1024, max_retries3, messages[ { role: user, content: Im responding to a students question. Here is the link to the documentation: {{doc_link1}} and {{doc_link2}}, } ], template_inputs{ doc_link1: https://python.useinstructor.com/docs/tutorial/tutorial-1, doc_link2: https://jxnl.github.io/docs/tutorial/tutorial-2, }, response_modelEmail, ) print(email)关于模板化提示词templated inputs上面消息内容中的{{doc_link1}}、{{doc_link2}}是 Parea 支持的模板语法运行时 Parea 会用template_inputs字典中的值替换占位符并在 Trace 中把「模板 实际输入值」分开记录方便审计与复用。这与instructor自有的模板能力在理念上互补——仓库中 instructor/v2/core/templating.py 同样实现了{{...}}风格的 kwargs 模板渲染templated_inputs/context变量注入因此使用 Parea 时二者可以配合模板在客户端侧渲染实际变量值由 Parea 记录进 Trace。查看 Trace重试分组与验证错误评分运行上述代码后进入 Parea 控制台查看该次执行生成的 Trace可以看到三个关键信息左侧边栏所有相关的 LLM 调用被归组到一条名为instructor的 Trace 下包括重试产生的子调用中间区域根 Trace 将templated_inputs作为输入、将最终创建的Email对象作为输出可视化展示右侧边栏底部任何验证错误都被捕获并作为该 Trace 的评分score记录从而可以在仪表盘中可视化、在表格中按错误筛选。如上图所示虽然邮件最终成功生成但过程中发生了一次验证失败这次失败引入了额外的成本与延迟——这正是instructor的「校验—重试」机制在实际运行中的代价也是观测平台最能体现价值的场景。通过把验证错误计数作为评分团队可以直接在 Parea 的仪表盘上按时间维度观察instructor的平均验证错误数变化趋势这类指标对追踪结构化输出的质量退化非常有效例如修改提示词或模型版本后若验证错误数明显上升说明生成质量在下降可以及时回滚或补充 few-shot 示例。用 Form Mode 标注响应并导出微调数据当需要让领域专家SME标注响应以用于微调时Parea 提供标注队列annotation queue。对非开发者而言直接编辑包含工具调用/函数调用的 JSON 对象极易出错因此 Parea 提供了Form Mode用户只需安全地填写表单而不是手改 JSON标注后的数据即可导出用于微调。标注完成后可以用 Python 代码把数据集导出为 JSONL 文件from parea import Parea p Parea(api_keyos.getenv(PAREA_API_KEY)) dataset p.get_collection(DATASET_ID) # 替换 DATASET_ID 为实际数据集 ID dataset.write_to_finetune_jsonl(finetune.jsonl) # 将数据集写入 JSONL 文件得到finetune.jsonl后即可交给instructor的 CLI 发起微调任务instructor jobs create-from-file finetune.jsonl微调 CLI 的可选参数instructor jobs create-from-file并非只能使用默认值完整帮助参见 docs/cli/finetune.md$ instructor jobs create-from-file --help Usage: instructor jobs create-from-file [OPTIONS] FILE Create a fine-tuning job from a file. ╭─ Arguments ───────────────────────────────────────────────╮ │ * file TEXT 待微调文件的路径 [required] │ ╰───────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────╮ │ --model TEXT 微调基座模型 │ │ [default: gpt-4o-mini] │ │ --poll INTEGER 轮询间隔秒 │ │ [default: 2] │ │ --n-epochs INTEGER 训练轮数 │ │ --batch-size TEXT 批大小 │ │ --learning-rate-multiplier TEXT 学习率倍率 │ │ --validation-file TEXT 验证集文件路径 │ │ --model-suffix TEXT 模型标识后缀 │ │ --help 显示帮助信息 │ ╰───────────────────────────────────────────────────────────╯一个带完整超参数的调用示例$ instructor jobs create-from-file finetune.jsonl \ --validation_file validation.jsonl \ --n_epochs 3 \ --batch_size 16 \ --learning_rate_multiplier 0.5注意instructor jobs系列命令假设环境中已设置OPENAI_API_KEY环境变量。上传与查看文件、监控任务状态可配合instructor files list与instructor jobs list使用其中jobs list会以表格形式展示任务状态并每 5 秒自动刷新。小结从观测到微调的闭环通过本文可以看到 Parea 与instructor的组合带来了一条完整的工作流两行代码接入p.wrap_openai_client(client, instructor)instructor.from_provider(...)既有结构化输出能力又有全链路追踪透明的重试观测所有重试子调用自动归组为单条 Trace验证失败带来的额外成本与延迟一目了然验证错误指标化校验失败计数与字段被自动记录为 Trace 评分支持仪表盘可视化与表格筛选低门槛标注与微调Form Mode 让非开发者也能安全标注函数调用响应导出 JSONL 后直接用instructor jobs create-from-file发起微调。这套链路把「观测 → 定位 → 标注 → 微调」串在一起让结构化输出应用的质量改进不再是黑盒。若想进一步了解微调 CLI 的完整命令与参数可继续阅读 docs/cli/finetune.md关于instructor客户端工厂与重试机制的实现细节可查阅 instructor/v2/auto_client.py 与 instructor/v2/core/retry.py。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考