Apache Burr 常用 CLI 命令与工具详解
Apache Burr 0.42.0 CLI 命令详解:burr 主命令选项、burr-demo 演示服务、burr-test-case 测试用例生成及三个管理工具,含全部 help 回显与实测用例输出。
Apache Burr 常用 CLI 命令与工具详解
目标:以 burr 0.42.0(实际安装主体 apache-burr 0.42.0)为基线,详解 Apache Burr 随包安装的全部 7 个 CLI 命令入口,覆盖 Web UI 服务、演示服务、测试用例生成与发布管理工具,给出完整 help 回显与实测用例输出。以下命令与回显均在真实环境逐步实测(Ubuntu 22.04,Python 3.10.12)。
一、CLI 工具总览
burr[start] 安装完成后共提供 7 个命令入口,均位于虚拟环境 bin 目录:
| 命令 | 对应入口函数 | 作用 |
|---|---|---|
| burr | cli_run_server | 启动 Web UI 服务 |
| burr-admin-server | cli_run_server | 管理后台服务(与 burr 同一实现) |
| burr-demo | cli_demo_server | 启动演示服务 |
| burr-test-case | cli_test_case | 生成测试用例 |
| burr-admin-build-ui | cli_build_ui | 构建前端静态资源 |
| burr-admin-generate-demo-data | cli_generate_demo_data | 生成演示数据 |
| burr-admin-publish | cli_build_and_publish | 打包发布到仓库 |
版本说明:burr 未提供 version 子命令,实测 burr version 回显:
Usage: burr [OPTIONS]
Try 'burr --help' for help.
Error: Got unexpected extra argument (version)
版本查询请使用 pip show apache-burr。
二、burr 主命令:Web UI 服务
完整帮助实测回显:
Usage: burr [OPTIONS]
Options:
--port INTEGER Port to run the server on
--dev-mode Run the server in development mode
--no-open Run the server without opening it
--no-copy-demo_data Don't copy demo data over.
--host TEXT Host to run the server on -- use 0.0.0.0 if you want
to expose it to the network
--backend [local|s3] Backend to use for the server.
--help Show this message and exit.
启动命令:
burr --no-open --port 7241 --host 0.0.0.0
启动日志实测回显(关键行):
INFO | burr.cli.__main__:_run_server:170 - Starting server on port 7241
INFO | burr.cli.__main__:_run_server:178 - Copying demo data over to /root/.burr
INFO | burr.cli.__main__:_command:59 - Running command: /opt/burr-demo/.venv/bin/python3 -m uvicorn burr.tracking.server.run:app --port 7241 --host 0.0.0.0
INFO: Uvicorn running on http://0.0.0.0:7241 (Press CTRL+C to quit)
服务端主要 HTTP 接口实测回显:
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:7241/ready
200
curl -s http://127.0.0.1:7241/api/v0/version
{"version":"0.42.0"}
项目列表接口 /api/v0/projects 返回 5 个项目:demo_counter、demo_chatbot、demo_conversational-rag、demo_chatbot_with_traces、burr-quickstart;/openapi.json 提供完整 API 文档,包含 /api/v0/{project_id}/{partition_key}/apps 等路径。验证结果:服务启动与接口访问正常。
三、burr-admin-server:管理后台服务
burr-admin-server 与 burr 指向同一入口函数 cli_run_server,帮助输出完全一致(见上文)。二者均用于启动 Web UI 服务,日常使用 burr 即可。
四、burr-demo:演示服务
完整帮助实测回显:
Usage: burr-demo [OPTIONS]
Options:
--port INTEGER Port to run the server on
--help Show this message and exit.
启动命令:
burr-demo --port 7243
启动日志实测回显(关键行):
INFO | burr.cli.__main__:_run_server:170 - Starting server on port 7243
INFO | burr.cli.__main__:_run_server:178 - Copying demo data over to /root/.burr
INFO | burr.cli.__main__:_command:59 - Running command: /opt/burr-demo/.venv/bin/python3 -m uvicorn burr.tracking.server.run:app --port 7243 --host 127.0.0.1 --reload
INFO: Will watch for changes in these directories: ['/opt/burr-demo']
INFO: Uvicorn running on http://127.0.0.1:7243 (Press CTRL+C to quit)
INFO: Started reloader process [327] using StatReload
INFO: Application startup complete.
INFO: 127.0.0.1:60098 - "GET /demos/chatbot/ready HTTP/1.1" 200 OK
INFO: 127.0.0.1:60104 - "GET /ready HTTP/1.1" 200 OK
演示服务以 127.0.0.1 为默认监听地址并启用 --reload 热重载,额外提供 /demos/<示例名>/ready 等演示应用端点,就绪检查返回 200。验证结果:演示服务正常。
五、burr-test-case:测试用例生成
完整帮助实测回显(click 框架在 ARGS 后附省略点表示参数可重复,此处按规范省略该标记):
Usage: burr-test-case [OPTIONS] COMMAND [ARGS]
Test case related commands.
Options:
--help Show this message and exit.
Commands:
create Create a test case from a persisted state.
create 子命令帮助实测回显:
Usage: burr-test-case create [OPTIONS]
Create a test case from a persisted state.
Does two things:
1. Pulls data specified and saves it/prints to console. 2. Prints a pytest
test case to the console for you to cut and paste.
See examples/test-case-creation/notebook.ipynb for example usage. See
examples/test-case-creation/test_application.py for details.
If you have custom serialization/deserialization then pass in the name of a
python module, or a path to a python file, to import with your custom
serialization/deserialization registration functions. This will be imported
so that they can be registered.
Note: - when burr fails, then the state retrieved for a sequence ID is
the state at the start of the sequence ID. The fixture created will
only have input state. - when burr completes successfully, then the
state retrieved for a sequence ID is the final modified state. The
fixture created will have input and output state, as we will grab the prior
sequence ID's state as the input state. - we strip any keys
prefixed with __ from the state to avoid exposing private keys in the test
case.
Options:
--project-name TEXT Name of the project. [required]
--partition-key TEXT Partition key to look at.
--app-id TEXT App ID to pull from. [required]
--sequence-id TEXT Sequence ID to pull. [required]
--target-file-name TEXT What file to write the data to. Else print to
console.
--serde-module TEXT Python file or fully qualified python module to
import for custom serialization/deserialization.
--action-name TEXT Provide name of the action for the test case.
Defaults to the action name at the sequence ID.
--help Show this message and exit.
实测命令(基于快速入门应用落盘轨迹):
burr-test-case create --project-name burr-quickstart --app-id 1b853a06-13d9-44e2-83a0-55897f602302 --sequence-id 3 --target-file-name /tmp/tc.json
实测回显(关键行):
Action was successful so loading initial and expected state into test fixture.
Writing data to file /tmp/tc.json
Add the following to your test file:
import pytest
from burr.core import state
from burr.testing import pytest_generate_tests # noqa: F401
@pytest.mark.file_name("/tmp/tc.json")
def test_summarize(input_state, expected_state):
"""Function for testing the action"""
input_state = state.State.deserialize(input_state)
expected_state = state.State.deserialize(expected_state)
_, output_state = summarize(input_state) # exercise the action
assert output_state == expected_state
验证结果:--sequence-id 3 对应 summarize 动作,成功生成 pytest 测试用例并写出测试数据文件(生成代码中保留两处提示性注释,实际使用前按需替换)。
六、管理工具
6.1 burr-admin-build-ui
从源码构建 Web UI 前端静态资源,帮助实测回显:
Usage: burr-admin-build-ui [OPTIONS]
Build the UI artifacts from source.
Options:
--help Show this message and exit.
6.2 burr-admin-generate-demo-data
为 Web UI 生成演示数据,帮助实测回显:
Usage: burr-admin-generate-demo-data [OPTIONS]
generate demo data for the UI
Options:
--s3-bucket TEXT S3 URI to save to, will use the s3 tracker, not
local mode
--data-dir TEXT Local directory to save to
--unique-app-names Use unique app names
--no-clear-current-data Don't clear current data
--help Show this message and exit.
--s3-bucket 指定时走 S3 跟踪器写入对象存储;--data-dir 指定本地目录;--unique-app-names 为每次生成使用唯一应用名;--no-clear-current-data 保留既有数据不清空。
6.3 burr-admin-publish
打包并发布到 PyPI 仓库,帮助实测回显:
Usage: burr-admin-publish [OPTIONS]
Publishes the package to a repository
Options:
--prod Publish to pypi (rather than test pypi)
--no-wipe-dist Wipe the dist/ directory before building
--help Show this message and exit.
--prod 发布到正式 PyPI(默认测试 PyPI);--no-wipe-dist 在构建前不清空 dist/ 目录。验证结果:三个管理工具帮助信息均正常输出。
七、常见问题与参考链接
-
burr version 不存在:burr 无版本子命令,用 pip show apache-burr 查看版本;
-
Python 3.9 下 CLI 崩溃:burr CLI 源码使用 PEP 604 语法,需 Python 3.10 及以上;
-
未安装 start 扩展:CLI 报 Missing plugin start!,执行 pip install "burr[start]"。
-
Apache Burr 官方文档:https://burr.dagworks.io/
-
Apache Burr GitHub 仓库:https://github.com/apache/burr
-
PyPI apache-burr 包页面:https://pypi.org/project/apache-burr/
-
Apache Incubator Burr 项目页:https://incubator.apache.org/projects/burr.html