# @dynatrace-oss/dt-evals 中文文档

规范地址：https://npmcn.com/package/%40dynatrace-oss/dt-evals/

版本：0\.3\.7-alpha
npm 元数据更新时间：2026-11-10T13:27:42.939Z
中文译文更新时间：2026-11-13T02:46:11.039Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dynatrace-oss/dt-evals
原文对照：https://npmcn.com/package/%40dynatrace-oss/dt-evals/?lang=original
项目主页：https://github.com/dynatrace-oss/dt-evals#readme
源码仓库：https://github.com/dynatrace-oss/dt-evals

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：562 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.23\.4 \|\| ^24\.22\.1 \|\| \>=26\.12\.1
- 运行依赖：13 个
- 首次发布：2026-05-12T17:19:48.596Z
- 最新版本发布：2026-11-10T13:27:42.572Z
- 近 30 天下载量：11928（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

AI对Dynatrace的可观察性评价CLI

## 安装

```sh
npm install @dynatrace-oss/dt-evals
```

也可以使用：`pnpm add @dynatrace-oss/dt-evals`、`yarn add @dynatrace-oss/dt-evals`、`bun add @dynatrace-oss/dt-evals`

## README

# dt- evals - Dynatrace 评价 CLI 工具

**用于LLM应用的开源连续evals,以生产即时跟踪作为数据集.**

[![npm version](https://img.shields.io/npm/v/@dynatrace-oss/dt-evals/alpha?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/@dynatrace-oss/dt-evals) [![npm downloads](https://img.shields.io/npm/dm/@dynatrace-oss/dt-evals?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@dynatrace-oss/dt-evals) [![Build](https://github.com/dynatrace-oss/dt-evals/actions/workflows/ci-cli.yml/badge.svg?branch=main)](https://github.com/dynatrace-oss/dt-evals/actions/workflows/ci-cli.yml) [![License](https://img.shields.io/badge/license-Apache_2.0-blue?style=flat-square)](https://npmcn.com/package/%40dynatrace-oss/dt-evals/LICENSE) [![Node](https://img.shields.io/node/v/@dynatrace-oss/dt-evals/alpha?style=flat-square)](https://npmcn.com/package/%40dynatrace-oss/dt-evals/package.json)

> [![Watch the video](https://npmcn.com/package/%40dynatrace-oss/assets/dt-evals-welcome.gif)](https://www.youtube.com/watch?v=64WwV4K287g)
> 
> 📺 **见于行动:** [如何用 dt- evals 运行 LLM 评价](https://www.youtube.com/watch?v=64WwV4K287g) ——实事求是地通过拉出生产痕迹,用LLM评分,在Dynatrace读取结果.

`dt-evals` 专为那些想让Evals在真实流量上运行的团队提供聊天,RAG,副驾驶,代理工作流程,而不只是全程测试集.

如今,CLI同时使用Dynatrace作为微量源和评价结果商店. 它拉出 gen ai.\* 跨出你的活环境, 遮住记忆中的敏感数据, 与 LLM 判断器进行真实的制作互动, 检测分数随时间推移.

这意味着当一个分数下降或超值出现时,你不只是看到质量倒退,你可以通过完整的AI执行路径追溯到它:提示,检索上下文,模型调用,工具使用,耐用,失败,以及服务依赖.

在实践中,这为AI工程师提供了一个闭环,用于评价,可观察性,警示性,异常检测,以及针对他们已经用于操作系统的生产遥测的补救.

资料库还包括: `dt-eval-lib`,一个可重复使用的 TypeScript 评估引擎,用于直接在代码中运行相同的基于判断的度量衡,使用内置评价器目录或者您自己的自定义即时定义. 它也与更广泛的评价工作流程和可观察性堆栈,如Ragas,MLflow,或者Langfuse, 完全吻合,当你想与这个库一起协调或追踪这些系统中的等值.

```bash
npx @dynatrace-oss/dt-evals configure
npx @dynatrace-oss/dt-evals validate
npx @dynatrace-oss/dt-evals run --since 1h --sample 10 --concurrency 10
```

调色板 `--concurrency` (或 `judge.concurrency` 来控制有多少法官的电话是平行运行的—— 快速运行时,如果提供者限制你,就放弃。 默认为 5.

> 🎮 **在安装前看到它活着** —— 说 [**打开dt-evals游乐场仪表板**](https://wkf10640.apps.dynatrace.com/ui/apps/dynatrace.dashboards/dashboard/dynatrace.genai.observability.aiobservability) 我们的公众Dynatrace租户。 真正的评价与生产GENAI的痕迹相对比——每公分,随时间推移而变化,违反阈值,点击到原痕迹.

## 团队为什么使用它

-   在真正的生产痕迹上运行 而不是静态测试集
-   在Dynatrace中保留带有痕迹、日志、度量衡、仪表板和警报的eval结果
-   使用内置判断器衡量标准获取常见的 LLM 和代理失败模式
-   检测回归,漂移, 和越出得分的早期变化
-   从分数低到有端到端的AI可观察性
-   将故障与提示、检索、工具呼叫、延迟和依赖性相匹配
-   在 CI 、 app 代码和 dt- eval- lib 本地工作流程中重新使用相同的评价器目录
-   触发警报和同一评价管道的可选补救

## 软件包

| 软件包 | 它是为了什么 |
| --- | --- |
| `dt-evals` | 持续评估与Dynatrace的GenAI痕迹对照 |
| `dt-eval-lib` | 用于在测试、脚本和应用程序代码内进行基于法官的 evalls 的 TypeScript 库 |
| `dt-eval-engine` | 部署的eval工人和无服务器跑道者的核心运行时间 |

## 它会做什么

-   **15个内部法官衡量标准** 安全、地基、相关性、质量和检索质量
-   **统计漂移探测** 根据7天基准的先前评价分数
-   **灵活取样** 随机百分比,最新 `N`,或 `errors-only`
-   **PII 在法官打电话前蒙面** 电子邮件、电话号码、信用卡和SSN
-   **被评估的即时/答复被默认排除** 选择与 `storeEvaluatedPrompt` (见 [配置](https://npmcn.com/package/%40dynatrace-oss/dt-evals/#readme-configuration)(中文(简体) )
-   **OpenAI,Anthropic,Azure OpenAI,Google双子企业平台(Vertex AI),和贝德洛克支持** 为网关和代理设置可选的自定义基础 URL
-   **CI 友好运行** jSON 输出和非零退出代码
-   **本地运行历史** 清单、检查和出口流动
-   **预定运行** 储存在本地并可根据需要触发
-   **评估员检查和测试** 从CLI中
-   **类型脚本 API** 用于在代码中直接运行评估器目录

## 如何运作

```text
Dynatrace spans (gen_ai.*)
        |
        v
sample traces -> mask sensitive data -> score with LLM judge -> write business events
                                                                    |
                                                                    v
                                             query in DQL, dashboard, alert, export
```

目前的 CLI 路径是 Dynatrace 特定的 。 出品定位更宽泛:连续为AI-native工程团队提供eval,以活的LLM流量为真源.

## 所需资源

-   节点.js `>=20`
-   带有 GenAI 跨度或 OpenTelemetry 风格的 Dynatrace 环境 `gen_ai.*` 字段
-   您的判断提供者( OpenAI, Anthropic, Azure OpenAI, Google 双子企业平台( Vertex AI) 或 Bedrock)的证书

## 安装

```bash
npm install -g @dynatrace-oss/dt-evals
```

或者不安装就运行 :

```bash
npx @dynatrace-oss/dt-evals <command>
```

CLI 还自动装入一个本地 `.env` 当前工作目录中的文件.

## 快速启动

### 1\. 创建配置

互动设置 :

```bash
dt-evals configure
```

非交互设置 :

```bash
dt-evals configure \
  --env-url https://your-env.live.dynatrace.com \
  --api-token "$DT_API_TOKEN" \
  --provider openai \
  --api-key "$OPENAI_API_KEY" \
  --model gpt-4.1 \
  --since 1h \
  --output .dt-eval.yaml
```

### 2\. 验证设置

```bash
dt-evals validate
```

此检查 :

-   配置计划
-   同步连接
-   法官的可达性
-   评价器目录可用性

### 3\. 运行最近追踪的测试

```bash
dt-evals run --since 1h --sample 10 --concurrency 5
```

只运行一个评估器 :

```bash
dt-evals run --since 6h --metric faithfulness
```

预览作品

```bash
dt-evals run --since 1h --sample 5 --dry-run
```

## CLI 工作流程

### Eval生产运行

```bash
dt-evals run \
  --since 2h \
  --sample 20 \
  --concurrency 8 \
  --debug
```

### CI 质量回归门

```bash
dt-evals run --since 6h --metric relevance --ci
```

-   退出代码 `0`:没有违反门槛
-   退出代码 `1`: 一次或多次违反阈值

示例 GitHub 动作步骤 :

```yaml
- name: Run LLM eval gate
  run: npx @dynatrace-oss/dt-evals run --since 6h --metric faithfulness --ci
  env:
    DT_ENV_URL: ${{ secrets.DT_ENV_URL }}
    DT_API_TOKEN: ${{ secrets.DT_API_TOKEN }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
```

### 只运行漂移检测

```bash
dt-evals run --metric drift --since 24h
```

这使用了先前已经写给Dynatrace的评价结果,并将最近的窗口与7天的基准进行比较.

### 检查现有评价人员

```bash
dt-evals evaluators list
dt-evals evaluators show faithfulness
dt-evals evaluators test relevance
```

创建或删除自定义评估器 :

```bash
dt-evals evaluators add
dt-evals evaluators delete my-custom-eval
```

### 管理运行历史

```bash
dt-evals runs list --limit 20
dt-evals runs show run-2026-04-10T12-00-00-ab12cd34
dt-evals runs export --format csv --output runs.csv
```

运行记录在本地存储 `~/.dt-eval/runs.json`。 。 。 .

### 计划重复运行

```bash
dt-evals schedule add --name hourly-rag --cron "0 * * * *" --since 1h --sample 10
dt-evals schedule list
dt-evals schedule run <schedule-id>
dt-evals schedule disable <schedule-id>
dt-evals schedule enable <schedule-id>
dt-evals schedule delete <schedule-id>
```

列表为本地存储 `~/.dt-eval/schedules.json`。 。 。 .

### 检查当前状态

```bash
dt-evals status
dt-evals configure --show
```

## 图标

| 命令 | 说明 |
| --- | --- |
| `configure` | 交互或通过旗帜创建或更新配置 |
| `validate` | 检查配置、 Dynatrace 连接和判断提供者可用性 |
| `run` | 评价最近的 GenAI 跟踪 |
| `status` | 显示解析后的配置、 连接和上次运行摘要 |
| `evaluators` | 名单、检查、测试和管理评估人员 |
| `runs` | 查看和导出历史运行记录 |
| `schedule` | 创建并触发重复运行 |

全球旗帜 :

```text
--verbose    Enable verbose logs
--json       Emit structured JSON logs
```

`run` 旗帜 :

```text
--config <path>        Path to config file
--since <duration>     Trace lookback window, for example 1h or 24h
--sample <percent>     Percentage of traces to evaluate
--metric <name>        Run only one evaluator
--dry-run              Do not call the judge or write results
--ci                   JSON result output and exit 1 on threshold breach
--concurrency <n>      Parallel judge calls (overrides judge.concurrency in the config; default 5)
--store-evaluated-prompt   Include the evaluated prompt/response in bizevents (overrides storeEvaluatedPrompt in the config; default: false)
--debug                Per-step timing logs
```

## 配置

配置按此顺序解决:

| 优先权 | 来源 |
| --- | --- |
| 1个 | 环境变量 |
| 2个 | 项目配置, 通常 `.dt-eval.yaml` |
| 3个 | 全球配置, `~/.dt-eval/config.yaml` |
| 页:1 | 内建默认 |

### 示例配置

```yaml
schemaVersion: 3
name: travel-assistant-prod

dynatrace:
  environmentUrl: https://your-env.live.dynatrace.com
  dtctlContext: my-prod-context

judge:
  provider: openai
  model: gpt-4.1
  timeout: 30000
  maxRetries: 2
  concurrency: 5

scope:
  service: travel-assistant
  since: 1h
  operationNames: [chat, text_completion, generate_content]
  sampling:
    strategy: random
    percent: 10

metrics:
  enabled:
    - faithfulness
    - hallucination
    - relevance
    - answer-completeness
    - id: valid-json
      method: json_schema
      params:
        schema:
          type: object
          required: [answer]
    - id: no-refusal
      method: must_not_contain
      params:
        keywords: ["i cannot help", "i'm sorry"]
        mode: any
    - drift

alerts:
  thresholds:
    faithfulness: 0.7
    relevance: 0.7
    answer-completeness: 0.8

storeEvaluatedPrompt: false
```

无字符串条目和对象条目 `method` 使用配置 LLM-现判提供商. 决定性条目集 `method` 改为 `exact_match`, (中文(简体) ), `regex`, (中文(简体) ), `must_not_match`, (中文(简体) ), `json_schema`, (中文(简体) ), `must_contain`,或 `must_not_contain`。 。 。 . `exact_match` 比较跨度输出与字数 `params.expectedOutput` 在配置中定义 :

```yaml
metrics:
  enabled:
    - id: exact-answer
      method: exact_match
      params:
        expectedOutput: "OK"
        caseSensitive: false
        trim: true
```

默认情况下, 跑者只保留聊天/文本生成跨度 : `chat`, (中文(简体) ), `text_completion`,以及 `generate_content`配置 `scope.operationNames` 以缩小或扩展该保留列表,例如 `operationNames: [chat]`设置它 `[]` 只有在你故意想要时 禁用操作名过滤器.

抽样战略:

| 战略 | 示例 |
| --- | --- |
| 随机百分比 | `strategy: random`, (中文(简体) ), `percent: 10` |
| 最近的痕迹 | `strategy: latest`, (中文(简体) ), `count: 200` |
| 仅追踪出错 | `strategy: errors-only` |

### 交叉租户配置

`dynatrace.environmentUrl` 编号 : `dynatrace.apiToken` 描述一个租户 既能处理读写. 分拆它们——从 GenAI 取出跨度 一个租户,然后写给另一个租户的评价文具——使用 `origin` (读) 财务报告和审定财务报表 `destination` (写作):

```yaml
dynatrace:
  origin:
    environmentUrl: https://prod.live.dynatrace.com
  destination:
    environmentUrl: https://eval-results.dev.apps.dynatracelabs.com
```

顶级 `environmentUrl` 编号 : `apiToken` (如果存在的话)充当倒计时——如果 中,使用顶级值。 所以,一个租户 配置只是由两侧空出而成的交叉租户形式.

这个 `validate` 命令探测器,包括真实的 `fetch spans | limit 1` 与来源相对应以捕捉缺失 `storage:spans:read` 尝试运行前的镜框.

### 所需的符号范围

| 范围 | 所需经费 |
| --- | --- |
| `storage:spans:read` | 读取 GenAI 跨度( 来源) |
| `storage:buckets:read` | 圣杯先决条件——没有这个, DQL 默回空结果 |
| `storage:bizevents:read` | 漂流探测基线(读取过 eval bizevents) |
| `storage:events:write` | 将评价结果写成bizevents(目的地) |
| `storage:metrics:write` | 编写评价指标 _(可选)_ |
| `storage:logs:read` | `dt-evals validate` 连接探测器 |

对于 `dt-evals alerts apply` (Dynatrace Workflows),在 dtctl OAuth 客户端上额外给予这些:

| 范围 | 所需经费 |
| --- | --- |
| `automation:workflows:read` | `list`, (中文(简体) ), `diff`,具有 `apply` |
| `automation:workflows:write` | `apply`, (中文(简体) ), `delete` |
| `automation:workflows:run` | 从 UI 手动执行 _(可选)_ |

### 自定义跨字段映射

默认情况下,CLI会读取OTel GenAI semconv (`gen_ai.input.messages`, (中文(简体) ), `gen_ai.output.messages`(中文(简体) ). 它也探测到一个 小规模的后遗症属性(`gen_ai.prompt.N.*`, (中文(简体) ), `gen_ai.completion.0.content`),用于与更古老的发射器相兼容. 若为 不同属性名称下的 LLM I/O 显示 实例 :`llm.input_messages`, (中文(简体) ), `llm.output_messages`, (中文(简体) ), `llm.model_name`——将CLI通过 `scope.spanFields`见 [`dynatrace-ai-agent-instrumentation-examples`](https://github.com/dynatrace-oss/dynatrace-ai-agent-instrumentation-examples) 用于端到端的仪器示例. 每个条目接受单一属性或候选人名单;第一个 非正负值胜出,内置默认值作为倒置附加.

**例1——明确的遗产产出绘图**数字 :

```yaml
scope:
  service: pydantic-ai-music-agent
  spanFields:
    output: gen_ai.completion.0.content
```

默认输出映射使用 `gen_ai.output.messages`。 。 。 . `spanFields` 让我们 您明确选择遗产或特定排放属性.

**例2——OTel跨度不跟随GenAI SemConv(开放推论):**

```yaml
scope:
  service: my-openinference-service
  since: 30m
  spanFields:
    input: [llm.input_messages, input.value]
    output: [llm.output_messages, output.value]
    model: llm.model_name
```

OpenInformation 通常存储聊天打开 `llm.input_messages` 编号 : `llm.output_messages` 和纯文本有效载荷 `input.value` 编号 : `output.value`,所以列出两者都保持了绘图的回弹性 仪器.

### 按属性过滤跨度

`scope.filters` 将 DQL 获取缩小为带有特定属性的跨度 数值。 密钥是跨属性名称; 每个值是一个单一值或一个 列表中选择一个选项。 分开的密钥被拼接在一起,一个密钥的值列表是 通过 `in()`。过滤在圣杯中发生,所以被排除的跨度永远不会 转移或判断.

**例1——在多代理服务中隔离管弦乐手**数字 :

```yaml
scope:
  service: support-orchestrator
  filters:
    gen_ai.agent.name: router
```

`service` 单凭一个管弦乐师和副代理人是分不开的 当两者在同一个服务中运行并发出相同的 `gen_ai.operation.name`。 。 。 .

**例2——限制有标记的生产流量**数字 :

```yaml
scope:
  service: travel-assistant
  filters:
    deployment.environment: production
    gen_ai.request.model: [gpt-4.1, gpt-4.1-mini]
```

属性名称被传递到 DQL 逐字记录中, 因此一个未知或错误的 属性表面为来自圣杯的 DQL 错误而不是被验证 当地.

### 按计量输入路径

计量条目 `metrics.enabled` 接受字符串 id (遗产) 窗体)或对象 `inputs` 覆盖横跨地段的 提供每个评估员输入槽。 当一个度量衡得分时,这是有用的 只谈了一部分——比如说. `user-frustration` 评价用户的 转身与外界隔绝,而不是合并记录:

```yaml
metrics:
  enabled:
    - faithfulness                                  # plain string form
    - id: user-frustration
      inputs:
        input: userPrompt
    - id: hallucination
      inputs:
        context: context
```

可用峡谷域 : `input`, (中文(简体) ), `output`, (中文(简体) ), `context`, (中文(简体) ), `systemInstruction`, (中文(简体) ), `model`, (中文(简体) ), `userPrompt` (最新的用户作用提示槽,取自 `gen_ai.prompt.N.role == "user"`) (中文(简体) ). `context` 没有内建默认跨度 属性——如果一个跨度不提供,则省略评价上下文,除非 指定路径 `inputs.context` 别的地方.

### 完整实例

完整 `.dt-eval.yaml` 结合一切——图谋相撞,风俗相通 横跨实地绘图、每度量输入路径、取样、警报:

```yaml
schemaVersion: 3
name: travel-assistant-prod

dynatrace:
  environmentUrl: https://your-env.live.dynatrace.com
  # apiToken loaded from DT_API_TOKEN env var

judge:
  provider: azure-openai
  model: gpt-4.1-mini
  # apiKey, baseUrl, apiVersion loaded from AZURE_OPENAI_* env vars

scope:
  service: travel-assistant
  since: 1h
  operationNames: [chat, text_completion, generate_content]
  sampling:
    strategy: latest
    count: 50
  spanFields:
    context: span.context
    # input, systemInstruction, model use built-in defaults

metrics:
  enabled:
    - faithfulness
    - relevance
    - hallucination
    - answer-completeness
    - id: user-frustration
      inputs:
        input: userPrompt
    - id: no-refusal
      method: must_not_contain
      params:
        keywords: ["i cannot help", "i'm sorry"]
        mode: any

alerts:
  thresholds:
    faithfulness: 0.7
    relevance: 0.7
    answer-completeness: 0.8
    user-frustration: 1
```

有用的环境变量:

```bash
DT_ENV_URL=https://your-env.live.dynatrace.com
DT_API_TOKEN=dt0c01.xxxxx
DT_DTCTL_CONTEXT=my-prod-context

# Cross-tenant overrides (optional — when set, these win over the top-level pair)
DT_ORIGIN_ENV_URL=https://prod.live.dynatrace.com
DT_ORIGIN_API_TOKEN=dt0s16.xxxxx
DT_DESTINATION_ENV_URL=https://eval-results.dev.apps.dynatracelabs.com
DT_DESTINATION_API_TOKEN=dt0s16.yyyyy

JUDGE_PROVIDER=openai
JUDGE_MODEL=gpt-4.1

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://your-gateway.example.com/v1

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=https://your-proxy.example.com

# Google Gemini Enterprise Platform (Vertex AI)
GOOGLE_API_KEY=...
# Or authenticate via Workload Identity / Application Default Credentials instead of an API key.
# Set the target project and region (or judge.project / judge.location in config):
GOOGLE_CLOUD_PROJECT=my-gcp-project
GOOGLE_CLOUD_LOCATION=global
```

## Dynathrace 结果

评价结果作为商务活动与 `event.type == "gen_ai.evaluation.result"`。 。 。 .

重要领域包括:

| 外地 | 含义 |
| --- | --- |
| `gen_ai.evaluation.name` | 例如,评估者名称 `faithfulness` |
| `gen_ai.evaluation.score.value` | 数字分数 |
| `gen_ai.evaluation.score.label` | `pass` 或者说 `fail` |
| `gen_ai.evaluation.score.explanation` | 法官的简短摘要 |
| `dt.eval.run_id` | 评价运行标识符 |
| `trace_id` | 源线索ID |
| `dt.service.name` | 配置时的服务过滤器 |

示例 DQL :

```dql
fetch bizevents
| filter event.type == "gen_ai.evaluation.result"
| summarize avg_score = avg(gen_ai.evaluation.score.value), by: { gen_ai.evaluation.name }
| sort avg_score asc
```

漂流结果被写回相同的事件类型 `gen_ai.evaluation.type == "drift"`。 。 。 .

## 内建评价员

`dt-evals` 拥有15个内置LLM的船舶判断评价员,加上漂移探测作为单独的统计度量.

| 评价员 | 措施 | 使用的字段 |
| --- | --- | --- |
| `answer-completeness` | 请求的所有部分是否得到答复 | `input`, (中文(简体) ), `output` |
| `bias` | 有害偏见或不公平的设定 | `input`, (中文(简体) ), `output` |
| `conciseness` | 答案是否避免填充和不必要的补注 | `input`, (中文(简体) ), `output` |
| `context-relevance` | 获取上下文的质量 | `input` |
| `factual-accuracy` | 利用世界知识的准确性 | `input`, (中文(简体) ), `output` |
| `faithfulness` | 答案是否基于所提供的上下文 | `input`, (中文(简体) ), `output` |
| `fluency` | 语法、清晰度和自然语言质量 | `input`, (中文(简体) ), `output` |
| `hallucination` | 无凭证或捏造的索赔 | `input`, (中文(简体) ), `output` |
| `output-prompt-injection` | 喷出的有效载荷在输出中排放到劫持下游毒剂 | `output` |
| `pii-leakage` | 答复中的个人识别信息 | `input`, (中文(简体) ), `output` |
| `prompt-injection` | 输入中的快速注射尝试 | `input` |
| `relevance` | 答案是否针对用户请求 | `input`, (中文(简体) ), `output` |
| `summarization-quality` | 简要忠诚、报道和简洁 | `input`, (中文(简体) ), `output` |
| `toxicity` | 有害、攻击性或不安全的产出 | `output` |
| `user-frustration` | 用户信件中的失败信号 | `input` |

### 确定性评价员(代码值)

不是每个检查都需要LLM. 添加一个 `method` 参数条目 `metrics.enabled` 运行一个快速,可复制,零成本 **代码 eval** 联合国 而不是LLM法官。 每个都给跨度输出打分 已通过(`1.0`)或失败(`0.0`) (中文(简体) ). 选择 `method` 保存默认 LLM-as-judge的行为,所以现有的配置不受影响.

可用方法: `exact_match`, (中文(简体) ), `regex`, (中文(简体) ), `must_not_match`, (中文(简体) ), `must_contain`, (中文(简体) ), `must_not_contain`,以及 `json_schema`。 。 。 .

**`exact_match` - 要求输出等于预期字符串**

```yaml
metrics:
  enabled:
    - id: matches-canonical-answer
      method: exact_match
      params:
        expectedOutput: "APPROVED"
        trim: true            # strip surrounding whitespace before comparing
        caseSensitive: false  # default true; set false to ignore case
```

**`must_contain` ——需要显示预期关键词**

```yaml
    - id: cites-a-source
      method: must_contain
      params:
        keywords: ["source", "reference", "according to"]
        mode: any          # any = pass if one is present; all = require every keyword
```

**`must_not_contain` 禁用或有害的词语**

```yaml
    - id: no-harmful-words
      method: must_not_contain
      params:
        keywords: ["harmful_word_1", "harmful_word_2", "harmful_word_3"]
        mode: any          # fail if ANY blocked word appears
        # matching is case-insensitive by default; set caseSensitive: true to change
```

**`must_not_match` —— 如果输出符合模式( 如 IP 地址被泄露) 失败**

```yaml
    - id: no-ip-leaked
      method: must_not_match
      params:
        pattern: "\\b(?:\\d{1,3}\\.){3}\\d{1,3}\\b"
```

**`regex` - 恰恰相反 `must_not_match`: 仅在输出匹配时通过**

```yaml
    - id: starts-with-ticket-id
      method: regex
      params:
        pattern: "^[A-Z]+-\\d+:"   # e.g. "AI-465: summary…"
        flags: "m"                 # ^ anchors each line, not just the string
```

**`json_schema` - 需要有效、结构完善的JSON**

```yaml
    - id: valid-response-object
      method: json_schema
      params:
        schema:
          type: object
          required: [answer]
```

> **说明:** `json_schema` 解析原始输出,所以输出必须是 **赤线** JSON——用减压栅栏包裹的对策(` ```json … ``` `)不会 剖析. `json_schema` 需要可选的 `ajv` 依赖,以及 `regex` 编号 : `must_not_match` 需要可选 `recheck` 依赖(用于ReDoS安全).

**示例配置 :** [`code-evals`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/code-evals/README.md) 应用这些 作为代理人最后答复的格式和政策门的方法; [`tool-call-accuracy`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/tool-call-accuracy/README.md) 指着他们 工具调用 `json_schema` 誓以辩驳, `must_not_match` 超过 结果——一名LLM法官参与辩论.

### 自定义评价员

您可以使用 `dt-evals evaluators add`,则 让它进入 `metrics.enabled` 像任何内置的评估员.

**实例自定义** (由交互式向导创建) 并在当地存储 :

```json
{
  "id": "answer-style",
  "version": "1",
  "name": "Answer Style",
  "description": "Checks whether the answer is concise, direct, and well structured.",
  "prompt": "Evaluate the answer style for this request. User request: {{input}} Answer: {{output}} Return a continuous score from 0.0 to 1.0.",
  "requiredFields": ["input", "output"],
  "scoring": {
    "type": "continuous",
    "range": [0, 1],
    "threshold": 0.7
  }
}
```

在您的 val 配置中启用 :

```yaml
metrics:
  enabled:
    - faithfulness
    - answer-style
```

有用命令 :

```bash
dt-evals evaluators add
dt-evals evaluators list
dt-evals evaluators show answer-style
dt-evals evaluators test answer-style
```

### 评价级别(代理轨迹)

默认情况下,每个跨度都单独得分(`scope.level: agent-span`)——一个 每个步骤的判决。 设定 `scope.level: agent-session` 评价 **整个代理 轨道** 相反: 跨度被分组为一个对话( 由 `gen_ai.conversation.id`后退为 `trace.id`一个法官打电话 翻过联合记录.

| `scope.level` | 单位得分 | 答复 |
| --- | --- | --- |
| `agent-span` (默认) | 一个跨/ 步 | 这一步是否正确? |
| `agent-session` | 一个对话/轨迹 | 代理人是否解决了整个请求,在一个失败的工具之后恢复, 保持前后的一致? |

完成、恢复和一致性只存在于各个步骤之间——每个阶段的分数 独自一人,他们是看不见的。 任何评价员,无论是内置还是自定义,都可以运行于 任何一级;会议一级 `keepPartTypes`, (中文(简体) ), `maxMessages`,以及 `maxConversations` 编成笔录.

**示例配置 :** [`agent-session`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/agent-session/README.md) 法官 整体对话的完整性; [`session-routing-accuracy`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/routing-accuracy/README.md) 升降机线路 精确到轨迹水平.

### 漂流探测

`drift` 将目前的分数分布与先前评价活动的7天基线进行比较.

当你关心逐渐出现的回归时使用它,而不只是单跑的阈值被突破.

## 实例

可运行, 已记录的示例配置在 [`examples/`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/)每一个 文件夹有自己的 README 解释何时使用和如何调整.

| 示例 | 演示 |
| --- | --- |
| [`code-evals`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/code-evals/README.md) | 确定出入/失效检查(`regex`, (中文(简体) ), `must_contain`, (中文(简体) ), `json_schema`,.)进行中,没有LLM法官 |
| [`agent-session`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/agent-session/README.md) | `scope.level: agent-session` ——分组多步对话(代理轨迹),判断整个笔录一次 |
| [`routing-accuracy`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/routing-accuracy/README.md) | 确定多代理的交接程序 每一个请求都会被传送到拥有它的代理 |
| [`tool-call-accuracy`](https://npmcn.com/package/%40dynatrace-oss/dt-evals/examples/tool-call-accuracy/README.md) | 正在检查一个工具呼叫 - `json_schema`编号 :`must_not_match` 其论据和结果,加上一名LLM法官,以判断是否用忠实的论据调用正确的工具 |

## 类型脚本库

资料库还包括: [`dt-eval-lib`](https://npmcn.com/package/%40dynatrace-oss/dt-eval-lib/README.md) ——一个独立的TypeScript包,用于在没有CLI的情况下在代码,测试和CI管道中直接运行同一种基于判事的度量衡. 它支持所有六个提供者和完整的内置评价员目录.

## PII 处理

对于CLI追踪评价运行,以下内容在发送到外部判断模型之前被遮掩入内存:

-   电子邮件地址
-   电话号码
-   信用卡号码
-   社会保障号码

原始值不通过 CLI 路径发送给法官.

## 数据期望

CLI默认读取 OTel GenAI semconv 字段:

| 条形领域 | 默认属性已读取 |
| --- | --- |
| `input` | `gen_ai.input.messages` |
| `output` | `gen_ai.output.messages` |
| `model` | `gen_ai.request.model` |
| `systemInstruction` | `gen_ai.system_instruction` |

这使得 CLI 适合使用 OpenTeleometry 设备的应用程序 GenAI公约。 用于其他追踪计划——包括Open Information—— 使用情况 `scope.spanFields` 以映射其属性到峡谷域 页:1 OpenInference 通常使用属性, 如 `llm.input_messages`, (中文(简体) ), `llm.output_messages`, (中文(简体) ), `input.value`, (中文(简体) ), `output.value`,以及 `llm.model_name`. 一组小的后退属性 (单位:千美元)`gen_ai.prompt.<n>.content/role`, (中文(简体) ), `gen_ai.completion.0.content`) 也为 探测到与更老的发射器的相容性. 见 [`dynatrace-ai-agent-instrumentation-examples`](https://github.com/dynatrace-oss/dynatrace-ai-agent-instrumentation-examples) 例如,仪器.

## 地方发展

```bash
# from the repo root — install all workspace dependencies
npm install

npm run build --workspace=dt-eval-lib
npm run build --workspace=dt-eval-cli
```

本地运行, 无需构建 :

```bash
npm run dev -- configure
npm run dev -- run --since 1h --dry-run
```

运行测试 :

```bash
npm test
```

## 捐款

欢迎提出问题和拉动请求.

如果你想努力进行更大的变革,首先打开一个问题,以便在执行开始之前明确方向.

## 许可证

[Apache 2.0 (英语)](https://npmcn.com/package/%40dynatrace-oss/dt-evals/LICENSE)

## 常见问题

### @dynatrace-oss/dt-evals 是什么？

AI对Dynatrace的可观察性评价CLI

### 如何安装 @dynatrace-oss/dt-evals？

在项目目录运行 npm install @dynatrace-oss/dt-evals，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 dt-evals，可以用 npx dt-evals 直接运行。

### @dynatrace-oss/dt-evals 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dynatrace-oss/dt-evals 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dynatrace-oss/dt-evals 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.23\.4 \|\| ^24\.22\.1 \|\| \>=26\.12\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dynatrace-oss/dt-evals 可以商用吗？

@dynatrace-oss/dt-evals 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dynatrace-oss/dt-evals 的下载量有多少？

根据 npm 官方下载统计，@dynatrace-oss/dt-evals 在 2026/10/13 – 2026/11/11 这 30 天内被下载 11,928 次，日均约 398 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dynatrace-oss/dt-evals 还在维护吗？

最新版本 0\.3\.7-alpha 发布于 2026/11/10（3 天前）；至今共发布 35 个版本，其中过去 12 个月发布了 35 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。