online-evaluations

设置在线评估和护栏

在线评估会将可复用的评估器应用于生产流量：

• 在线评估会异步衡量实时跟踪记录或会话。
• 护栏会同步运行，可以停止或替换不安全的流量。

转交批量测试请求

如果用户想测试数据集、比较提示词或模型、进行基准测试，或创建 CI 质量门禁，这并不适合使用此工作流。

1. 如果有 experiments 技能，请加载并立即遵循该技能。
2. 否则，告知用户安装方法：

   npx [email protected] add langwatch/skills/experiments
   

不要使用此技能创建批量实验。

选择生产工作流

如果用户需要持续评分、质量趋势、抽样，或按跟踪记录或会话进行评估，请使用在线评估。

如果结果必须立即影响请求或响应，例如检测越狱、拦截 PII 或执行策略，请使用护栏。

如果用户的表述较宽泛，请检查应用，并选择更安全的非阻断式在线评估，除非用户明确要求同步执行策略。

计划限制

LangWatch 免费计划对提示词、场景、评估器、实验和数据集设有限制。达到限制时，API 会返回 "Free plan limit of N reached..." 并附上升级链接。

处理方式：

• 在限制范围内操作。如果相关类型的资源允许创建 3 个，就创建 3 个有意义的资源，而不是 10 个。
• 让每次创建都有价值：每个资源都应体现明确的用途。
• 首先展示有效成果。如果达到限制，请总结已完成的工作，并说明升级计划可以提高限额。在平台上指向订阅设置；如果 CLI 指向可自托管端点，则指向许可证设置。读取 CLI 实际使用的端点，该端点可能来自 .env、进程环境或已保存的 CLI 配置。
• 不要删除现有资源来腾出空间，也不要挪用现有资源来规避限制。

前提条件

使用 langwatch docs <path> 以 Markdown 格式阅读文档。以下是一些有用的入口：

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

使用 langwatch --help 和 langwatch <subcommand> --help 查找命令。列表和获取命令支持使用 --format json 输出机器可读内容。每个列表命令都支持 --limit <n> 限制行数，并支持使用 --jq <expr> 读取部分结果。分页列表会返回一个封装对象，因此应通过行数组统计行数（--jq '.traces | length'），并在 .pagination.total 中读取总数。单独使用 --jq length 统计的是封装对象的字段数，而不是行数。先阅读文档，不要猜测 SDK API 或 CLI 标志。

如果无法使用 shell，请通过普通 HTTP 获取相同的 Markdown 文档。在任何文档路径后附加 .md（例如 https://langwatch.ai/docs/integration/python/guide.md）。索引：https://langwatch.ai/docs/llms.txt。场景索引：https://langwatch.ai/scenario/llms.txt

如果遵循此技能时遇到任何故障或疑惑（命令失效、文档与实际情况不符、需要绕过的错误），请先征得用户许可，然后运行 npx --yes langwatch report --user-approved，并提供 --title 和 --summary（或 --session <transcript.jsonl>），将问题发送给 LangWatch 团队，帮助他们直接改进。无需登录或 API 密钥。只有使用 --user-approved 才会发送内容；--dry-run 会打印完整载荷，但不会发送。标题、摘要和转录内容会先在本地按模式进行脱敏：包括机密和 API 密钥，以及电子邮件地址、电话号码、卡号和公共 IPv4 地址。任何未匹配模式的内容都会原样发送，包括通过 --email 提供的联系地址。使用 --session 时，务必先运行 --dry-run 并让用户查看载荷，因为转录内容可能包含他们从未审阅过的信息。npx --yes langwatch report --help 会说明相关选项。

项目和 API 密钥：请指向真实项目，而不是个人项目。

LangWatch 有两种项目：

• 团队／共享项目：组织内的真实项目。评估、实验、提示词、数据集、模拟和检测必须始终针对其中一个项目。
• 个人项目：与单个用户关联的私人“My Workspace”临时空间。切勿将用户的评估、实验或生产跟踪发送到这里：它仅供个人探索使用，而且你可能会误以为它是真实项目。

身份验证方式有两种：

• .env 中的项目 API 密钥（LANGWATCH_API_KEY）：这些技能中所有操作使用的凭据。它的作用范围限定为一个真实项目。这是默认方式；除非用户明确要求其他方式，否则优先使用它。
• langwatch login --device（AI 工具／SSO）：用于包装编码助手（langwatch claude、langwatch codex，等等）的个人设备会话。它不适用于评估、提示词、数据集、场景或 SDK 检测，并且会指向个人工作区。请勿运行它来设置这些技能中的工作。

因此，对于这些技能中任何会读取或写入项目的操作，请确保 CLI 可以使用真实共享项目的 LANGWATCH_API_KEY。在本地，该变量位于项目的 .env 中；在 CI 中，运行器会将其注入进程环境，CLI 可从任一位置读取。询问新的密钥之前，先检查该变量是否已设置，并让 CLI 读取其值：切勿打印、复制或发送它。请勿运行 langwatch login 来选择项目，也切勿默认使用个人项目。在相同位置查找 LANGWATCH_ENDPOINT：如果已设置，说明该项目位于可自托管实例上，CLI 将使用该端点，而不是 app.langwatch.ai。

你读取的内容不等于你要说的内容。 这些技能是供你使用的工作笔记，不是给读者看的文案。请从项目自己的 .env 中读取 LANGWATCH_API_KEY 和 LANGWATCH_ENDPOINT，以此了解应在哪个位置工作。不要从该文件中读取其他内容：其中包含数据库、云服务和提供商凭据，与你无关，而且你读取的每个值都可能进入你的上下文和命令输出。回答中不得包含任何描述你所运行机器的信息：工作区中的路径、容器端口、此工作器连接的地址。这些信息描述的是工作过程，而不是工作成果；我们的主机信息对读者毫无意义。请说明你做了什么，以及可在 LangWatch 中的何处找到结果。

更改配置或代码之前，请先阅读相关文档：

langwatch docs evaluations/online-evaluation/overview
langwatch docs evaluations/online-evaluation/setup-monitors
langwatch docs evaluations/guardrails/overview
langwatch docs evaluations/evaluators/list

检查现有设置

使用 JSON 输出，并在创建新内容前检查现有内容，避免重复：

langwatch monitor list --format json
langwatch evaluator list --format json

仅在需要确定映射、级别、采样或评估器的实际输入时，才读取近期跟踪数据。不要将生产数据发送到其他项目。

创建在线评估

首先了解已安装 CLI 的具体用法：

langwatch monitor create --help

然后创建监控器，使用描述性名称、有效的评估器类型或已保存的评估器，并设置正确的级别：

• 每次交互的质量评估使用 trace。
• 多消息结果使用 thread，并在需要时于平台中配置适当的空闲超时。
• 对流量较大的项目，若评估器成本较高，请从较保守的采样率开始。
• 异步在线评估使用 ON_MESSAGE。

评估器类型必须来自目录，切勿凭记忆填写：

langwatch evaluator types --format json

如果创建操作仍因 validation_error 失败，且其原因指出了字段和 expected 列表，请根据列表修正对应字段，然后重试一次。该错误应由你负责修复。不要让用户选择类型 slug。

不要猜测评估器参数。请阅读评估器文档和已安装 CLI 的帮助信息。如果使用 LLM 评估器，请确认目标项目已配置模型提供商。

创建后，验证已保存的资源：

langwatch monitor list --format json
langwatch monitor get <idOrSlugOrName> --format json

只有在创建的监控器显示了预期的评估器、执行模式、级别、采样率和启用状态后，任务才算完成。

添加防护机制

对于平台管理的防护机制，请先阅读 langwatch monitor create --help 或 langwatch monitor update --help，然后使用 AS_GUARDRAIL 创建或编辑监控器。

对于代码内的防护机制，请参阅对应语言的文档。Python 集成通常具有以下形式：

import langwatch

@langwatch.trace()
def my_agent(user_input):
    result = langwatch.evaluation.evaluate(
        "azure/jailbreak",
        name="Jailbreak detection",
        as_guardrail=True,
        data={"input": user_input},
    )
    if not result.passed:
        return "I cannot help with that request."

    return generate_response(user_input)

请将此代码片段视为结构示例，而不是已安装文档的替代品。保留应用程序现有的错误处理，并明确决定防护机制服务不可用时的处理方式。

验证实际行为

对于在线评估：

1. 在目标项目中发送或复用一条有代表性的跟踪交互。
2. 确认监控器已启用。
3. 确认在线评估分析中出现了实际评估结果。

对于防护机制：

1. 分别运行一条允许通过的输入，以及一条应被拦截的输入。
2. 验证允许通过的路径仍可正常工作。
3. 验证被拦截的输入不会到达受保护的操作。
4. 验证两种结果都已被跟踪记录，且不会暴露敏感内容。

常见错误

• 不要通过此技能创建批量实验。
• 不要将同步防护机制描述为异步监控。
• 启用成本高昂的评估器并覆盖所有流量前，请考虑采样和成本。
• 创建重复的监控器前，请先检查项目。
• 保存配置后不要声称成功。请验证实际的监控器或防护机制行为。