NOAA CLI完全指南：nooa start-dev追踪查看器、eval评测管道与配置管理
【免费下载链接】labs-OO-AgentsNVIDIA Object Oriented Agents: the Pythonic way to build AI Agents.项目地址: https://gitcode.com/gh_mirrors/la/labs-OO-Agents
NOAA CLI（命令为nooa）是 NVIDIA Object Oriented Agents 官方提供的命令行工具集，一条命令即可启动nooa start-dev 追踪查看器、运行nooa eval 评测管道，并用nooa config管理多层级模型配置。本指南面向新手，带你 10 分钟跑通这套 AI Agent 开发调试工具链。
一、NOAA CLI 是什么？3 大核心能力
nooa-cli包为 NVIDIA OO Agents 框架 提供统一的nooa命令，内置三大能力：
| 能力 | 命令 | 解决什么问题 |
|---|---|---|
| 📊 追踪查看器 | nooa start-dev | 在浏览器里可视化 Agent 的每次 LLM 调用与执行轨迹 |
| 🧪 评测管道 | nooa eval | 用 YAML 配置批量跑 Agent 测试、自动打分 |
| ⚙️ 配置管理 | nooa config | 透明化展示模型别名配置链，支持"一键弹出"本地配置 |
此外还提供nooa traces（清理/统计 trace 文件）和nooa completion（shell 自动补全）。所有命令源码位于 packages/nooa-cli/src/nooa_cli/commands/，想深入可以看 commands/_template.py 了解如何扩展新命令。
二、最快安装方法：一条 uv 命令搞定
推荐用 uv 安装（也可pip install）：
uv add nooa-cli- 自动带入匹配的
nemo-oo-agents核心框架 - 想让 LLM 在 REPL 里直接用 pandas/numpy，加
[datascience]额外包：uv add "nooa-cli[datascience]" - 验证安装：
nooa --help应列出start-dev、eval、traces、config等子命令
三、nooa start-dev 追踪查看器使用教程
3.1 一键启动，浏览器即开
nooa start-dev启动后终端会打印类似信息：
NVIDIA OO Agents Viewer URL: http://localhost:5001 DB: ~/.config/nooa/traces.db浏览器打开http://localhost:5001即可查看 trace 与评测结果。实现逻辑在 start_dev.py：默认绑定 5001 端口，trace 数据默认存在~/.config/nooa/traces.db（SQLite）。
3.2 自定义端口与多实例并行
nooa start-dev --port 5002 # 换个端口 nooa start-dev --db /tmp/demo-traces.db # 指定独立的 trace 库--db参数让你能并排运行两个查看器——例如一个看日常开发 trace，一个专门看评测实验，互不干扰。
3.3 跨机器共享：token 访问链接
设置NOOA_VIEWER_AUTH_TOKEN环境变量后，启动时终端会打印一条一次性 bootstrap 链接：
Share: http://<host>:5001/?token=xxxx任何人打开该链接即兑换为会话 cookie，之后普通深链即可使用。⚠️ 该链接可读全部 trace，请勿外泄。
💡 若提示端口被占用，CLI 会自动用
lsof/ss帮你查出具体的占用进程 PID，省去手动排查。
四、nooa eval 评测管道：YAML 配置驱动 Agent 测试
nooa eval是对 eval_pipeline 的薄封装，所有参数原样透传，因此天然与评测管道保持同步（见 eval.py）。
4.1 编写评测配置 config.yaml
一个最小可用的评测配置（完整字段参考 config.yaml）：
name: capability models: gpt-4: model_name: openai/gpt-4 endpoint: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY max_tokens: 8192 agent_models: - gpt-4 output_dir: experiments/results test_suite: - name: sentiment agent: module: my_agents class: SentimentAgent method: classify_single data_file: data/sentiment.jsonl scorers: - name: exact_match class: ExactMatchScorer weight: 1.0内置两种打分器：ExactMatchScorer（精确匹配）和LLMJudgeScorer（LLM 按评分细则打分），也支持加权组合与自定义 Scorer。
4.2 常用运行姿势
nooa eval --config config.yaml # 跑全部 nooa eval --config config.yaml --test sentiment # 只跑单个测试 nooa eval --config config.yaml --runs 3 # 自一致性：每题跑3次 nooa eval --config config.yaml --limit 5 -q # 限5条 + 静默模式静默模式输出极简，适合 CI：
sentiment gpt-4: 4/4 ✓ TOTAL: 7/8 passed (87.5%) → experiments/my_eval_20251213_103000.noo-eval.jsonl结果写入.noo-eval.jsonl，每条含passed、output、expected、scores及指向详细 trace 的路径。
4.3 让评测 trace 直达查看器
设置OTLP_ENDPOINT后，trace 不再落盘，而是实时推送到 start-dev 查看器：
nooa start-dev & # 先启动查看器 export OTLP_ENDPOINT=http://localhost:5001/v1/traces nooa eval --config config.yaml --runs 3每次运行以独立实验名（如capability_20260309_080455_207319_r3_p40）出现在评测查看器中，方便逐样本回看 Agent 行为。
五、nooa config 配置管理：4 层优先级一眼看清
模型别名配置采用分层合并、后者覆盖前者的链式结构（实现在 config.py 与 src/nooa/layered_config.py）：
- 内置默认— 各包通过入口点注册的 YAML
- 用户配置—
~/.config/nooa/llm_config.yaml - 项目配置— 项目内
.nooa/llm_config.yaml - 环境变量—
NEMO_OO_LLM_CONFIG（最高优先级，逗号分隔多路径）
三个子命令覆盖日常全部场景：
nooa config show # 打印每层是否存在、贡献了多少别名、API Key 是否已设置 nooa config path # 打印用户级配置文件路径 nooa config eject # 把内置默认配置"弹出"到用户目录供本地修改show是排障利器：模型别名找不到时，它能告诉你别名来自哪一层、某个文件是否被高优先级层遮蔽；eject则拒绝覆盖符号链接和已有文件（需--force），对 dotfiles 用户非常友好。
六、nooa traces：trace 文件统计与清理
评测与调试会积累大量 JSONL 文件，nooa traces帮你管理（见 traces.py）：
nooa traces list # 列出 trace 目录 nooa traces stats # 查看文件数量与占用统计 nooa traces delete -n # 先演练（dry run） nooa traces delete --older-than 7 # 只删 7 天前的文件七、命令速查表与延伸阅读
| 命令 | 用途 |
|---|---|
nooa start-dev | 启动 trace + 评测统一查看器（默认 :5001） |
nooa eval --config ... | 运行评测管道，透传全部 eval_pipeline 参数 |
nooa config show / path / eject | 查看 / 定位 / 弹出配置文件 |
nooa traces list / stats / delete | trace 文件治理 |
nooa completion install | 安装 shell 自动补全 |
📌 延伸阅读：
- CLI 包说明：packages/nooa-cli/README.md
- 评测管道完整文档（Python API、打分器、数据格式）：util/eval_pipeline/README.md
- 模型配置与分层机制：docs/model-configuration.md
- 快速上手示例（含 tracing）：examples/quickstart/06_tracing.py
总结
NOAA CLI 把 AI Agent 开发中最琐碎的三件事——看 trace、跑评测、管配置——压缩成了三条直觉命令：nooa start-dev、nooa eval、nooa config。安装即用、YAML 驱动、分层配置，新手也能快速建立完整的 Agent 调试与评测闭环。现在就uv add nooa-cli开始体验吧！
【免费下载链接】labs-OO-AgentsNVIDIA Object Oriented Agents: the Pythonic way to build AI Agents.项目地址: https://gitcode.com/gh_mirrors/la/labs-OO-Agents
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
