zeroeval-install

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZeroEval Install and Integrate

ZeroEval安装与集成

Guide users from zero to production-ready ZeroEval integration: tracing, prompt management, and automated judges.

指导用户从零开始完成可用于生产环境的ZeroEval集成：链路追踪、提示词管理和自动评估器。

When To Use

适用场景

Setting up ZeroEval for the first time in any language.
Adding tracing/observability to an existing AI app, agent, or pipeline.
Migrating hardcoded prompts to
```
ze.prompt
```
with staged rollout (Python / TypeScript).
Choosing and configuring judges for automated evaluation.
Troubleshooting missing traces, broken feedback loops, or prompt metadata issues.

首次在任意语言中配置ZeroEval。
为现有AI应用、Agent或流水线添加链路追踪/可观测能力。
将硬编码提示词迁移到
```
ze.prompt
```
并实现分阶段上线（Python / TypeScript）。
选择并配置用于自动评估的评估器。
排查链路丢失、反馈循环断裂或提示词元数据相关问题。

Execution Sequence

执行流程

Follow these steps in order. Each step references a specific playbook in

references/

for deep details; load only the relevant playbook when needed.

按顺序执行以下步骤。每个步骤都引用了

references/

目录下的特定操作手册以获取详细信息；仅在需要时加载对应的操作手册。

Step 1: Detect Integration Path

步骤1：确定集成路径

Determine which integration path fits the user's setup:

Check for
```
pyproject.toml
```
,
```
requirements.txt
```
,
```
setup.py
```
, or
```
.py
```
files -> Python SDK path. Continue to Step 2.
Check for
```
package.json
```
,
```
tsconfig.json
```
, or
```
.ts
```
/
```
.js
```
files -> TypeScript SDK path. Continue to Step 2.
If the user's language has no ZeroEval SDK (Go, Ruby, Java, Rust, etc.), or they explicitly want to use the REST API or OpenTelemetry without an SDK -> Direct API / OTLP path. Hand off to the
```
custom-tracing
```
skill and stop here.
If both Python and TypeScript are present, ask the user which SDK to set up first.

确定适合用户环境的集成路径：

检测到
```
pyproject.toml
```
、
```
requirements.txt
```
、
```
setup.py
```
或
```
.py
```
文件 -> Python SDK路径，继续执行步骤2。
检测到
```
package.json
```
、
```
tsconfig.json
```
或
```
.ts
```
/
```
.js
```
文件 -> TypeScript SDK路径，继续执行步骤2。
如果用户使用的语言没有对应的ZeroEval SDK（Go、Ruby、Java、Rust等），或者用户明确希望不使用SDK直接调用REST API或OpenTelemetry -> 直接API / OTLP路径，转交给
```
custom-tracing
```
技能并终止当前流程。
如果同时存在Python和TypeScript环境，询问用户优先配置哪个SDK。

Step 2: Install and Initialize

步骤2：安装与初始化

Load the appropriate playbook:

Python: Read
```
references/python-integration-playbook.md
```
and follow the "Install and Initialize" section.
TypeScript: Read
```
references/typescript-integration-playbook.md
```
and follow the "Install and Initialize" section.

Minimum outcome:

ze.init()

runs without errors and the API key is configured.

加载对应的操作手册：

Python：读取
```
references/python-integration-playbook.md
```
并按照「安装与初始化」章节操作。
TypeScript：读取
```
references/typescript-integration-playbook.md
```
并按照「安装与初始化」章节操作。

最低要求：

ze.init()

可无错误运行，且API key已完成配置。

Step 3: Verify First Trace

步骤3：验证首次链路追踪

Make one LLM call through a supported integration and confirm a trace appears.

Python: Follow the "Verify First Trace" section of the Python playbook. If the user's agent produces multiple judged outputs per run, introduce
```
ze.artifact_span
```
(see "Artifact Spans" in the playbook).
TypeScript: Follow the "Verify First Trace" section of the TypeScript playbook.

Minimum outcome: at least one span is ingested (confirm via dashboard or debug logs).

通过支持的集成发起一次LLM调用，确认链路已生成：

Python：按照Python操作手册的「验证首次链路追踪」章节操作。如果用户的Agent每次运行会生成多个评估输出，可介绍
```
ze.artifact_span
```
（参考操作手册中的「Artifact Spans」章节）。
TypeScript：按照TypeScript操作手册的「验证首次链路追踪」章节操作。

最低要求：至少有一个span被成功摄入（可通过仪表盘或调试日志确认）。

Step 4: Suggest ze.prompt Migration

步骤4：建议进行ze.prompt迁移

If the user has hardcoded system prompts, propose migrating to

ze.prompt

for version tracking, A/B testing, and prompt optimization.

Follow the "ze.prompt Migration" section of the relevant SDK playbook.
Start with
```
from: "explicit"
```
(safe rollout mode — always returns your local content, but still registers the version via a network call), then graduate to auto mode.
Always place
ze.prompt()
inside the function or request handler where the prompt is used. It performs network I/O and must not run at module import time or during app startup. See the playbook's "Placement and Resilience" guidance.

For the full migration workflow including feedback wiring, judge linkage, staged rollout, and prompt optimization, use the

prompt-migration

skill.

如果用户存在硬编码的系统提示词，建议迁移到

ze.prompt

以实现版本追踪、A/B测试和提示词优化：

按照对应SDK操作手册的「ze.prompt迁移」章节操作。
首先使用
```
from: "explicit"
```
（安全上线模式——始终返回本地内容，但仍会通过网络请求注册版本），之后再切换到自动模式。
务必将
ze.prompt()
放在使用该提示词的函数或请求处理程序内部。它会执行网络I/O，禁止在模块导入阶段或应用启动时运行。参考操作手册的「放置规则与容错」指导。

如需包含反馈关联、评估器绑定、分阶段上线和提示词优化的完整迁移流程，请使用

prompt-migration

技能。

Step 5: Suggest Judges

步骤5：推荐评估器

Load

references/judges-playbook.md

and recommend starter judges based on the user's app pattern:

Customer support / chat agents
Extraction / classification pipelines
Coding copilots
Retrieval QA / RAG assistants

Minimum outcome: user understands binary vs scored judges and has a first judge created or planned.

加载

references/judges-playbook.md

，根据用户的应用模式推荐入门级评估器：

客户支持/聊天Agent
提取/分类流水线
编码副驾驶
检索问答/RAG助手

最低要求：用户理解二元评估器和评分评估器的区别，且已创建或计划创建首个评估器。

Step 6: Validate and Troubleshoot

步骤6：验证与排障

Run the final checklist. If any check fails, load

references/troubleshooting.md

for diagnostics.

```
ze.init()
```
completes without errors
At least one trace is visible in the dashboard (or debug logs confirm span flush)
```
ze.prompt
```
returns decorated content with prompt metadata (if adopted)
Feedback or judge evaluation path is wired (if judges are configured)

运行最终检查清单。如果任何检查不通过，加载

references/troubleshooting.md

进行诊断。

```
ze.init()
```
无错误完成
仪表盘中可见至少一条链路（或调试日志确认span已上报）
若已启用
```
ze.prompt
```
，返回的内容包含提示词元数据标记
若已配置评估器，反馈或评估器评估路径已打通

Key Principles

核心原则

Minimal first: get one trace working before introducing prompts or judges.
Staged rollout: always start
```
ze.prompt
```
with
```
from: "explicit"
```
, then auto, then
```
from: "latest"
```
.
Lazy prompt resolution: call
```
ze.prompt()
```
inside the function or request path where the prompt is used, never at module scope or import time. It performs network I/O and can block or timeout during startup.
Evidence over assumption: use
```
debug: true
```
/
```
ZEROEVAL_DEBUG=true
```
to confirm SDK behavior rather than guessing.
Cloud by default: the production API URL is
```
https://api.zeroeval.com
```
. Only use
```
http://localhost:8000
```
for local development with an explicit override.

最小可行优先：先成功上报一条链路，再引入提示词或评估器功能。
分阶段上线：
```
ze.prompt
```
始终先使用
```
from: "explicit"
```
，再切换到自动模式，最后再使用
```
from: "latest"
```
。
懒加载提示词：在使用提示词的函数或请求路径内部调用
```
ze.prompt()
```
，绝对不要在模块作用域或导入阶段调用。它会执行网络I/O，可能在启动阶段造成阻塞或超时。
重证据轻假设：使用
```
debug: true
```
/
```
ZEROEVAL_DEBUG=true
```
确认SDK行为，而非主观猜测。
默认使用云端服务：生产环境API地址为
```
https://api.zeroeval.com
```
。仅在本地开发且明确配置覆盖时使用
```
http://localhost:8000
```
。