跳到主要内容

追踪 OpenCode

MLflow Tracing 为 OpenCode 提供自动追踪功能。OpenCode 是一款基于终端的智能代理编程工具，支持包括 Claude、OpenAI、Google 和本地模型在内的多个 LLM 提供商。

OpenCode Tracing

配置 MLflow 插件后，MLflow 将自动捕获 OpenCode 对话的追踪记录，并将其记录到指定的 MLflow 实验中。追踪记录会自动捕获以下信息：

  • 用户提示词 (User prompts) 和助手回复
  • 工具使用情况（文件操作、bash 命令、代码编辑等）
  • 每次对话的计时和持续时间
  • Token 用量（输入、输出和总 Token 数）

设置​

OpenCode 追踪通过 @mlflow/opencode 插件和环境变量进行配置。

要求​

  • 已安装 OpenCode CLI
  • Node.js 运行时（用于插件）
  • @mlflow/opencode npm 包
  • 正在运行的 MLflow 追踪服务器

第 1 步：安装插件​

bash
npm install @mlflow/opencode

第 2 步：配置 OpenCode​

将插件添加到你的 opencode.json 文件中

json
{
  "plugin": ["@mlflow/opencode"]
}

步骤 3：设置环境变量​

在项目根目录下创建一个包含 MLflow 连接设置的 .env 文件。OpenCode 在启动时会自动加载 .env 文件，因此配置可以在会话之间保持不变

.env
bash
MLFLOW_TRACKING_URI=https://:5000
MLFLOW_EXPERIMENT_ID=123456

或者，你也可以在 shell 中设置它们

bash
export MLFLOW_TRACKING_URI=https://:5000
export MLFLOW_EXPERIMENT_ID=123456

第 4 步：启动 MLflow 服务器（如果尚未运行）​

你可以使用 Docker Compose 启动 MLflow 服务器，这不需要 Python 环境

bash
docker compose up -d

或者，如果你已经安装了 Python 和 mlflow

bash
mlflow server

第 5 步：运行 OpenCode​

bash
# Run OpenCode normally - tracing happens automatically
opencode

当 OpenCode 会话进入空闲状态（每次对话结束后）时，将自动创建追踪记录。

配置参考​

该插件完全通过环境变量进行配置

环境变量必需描述
MLFLOW_TRACKING_URI是MLflow 追踪服务器 URI（例如 https://:5000）
MLFLOW_EXPERIMENT_ID是用于记录追踪信息的实验 ID
MLFLOW_OPENCODE_DEBUG否设置为 true 可启用发送到 stderr 的调试日志

配置示例​

bash
# Local MLflow server
export MLFLOW_TRACKING_URI=https://:5000
export MLFLOW_EXPERIMENT_ID=0

# Remote MLflow server
export MLFLOW_TRACKING_URI=http://mlflow.example.com:5000
export MLFLOW_EXPERIMENT_ID=123456

# Databricks MLflow
export MLFLOW_TRACKING_URI=databricks
export MLFLOW_EXPERIMENT_ID=123456789

令牌使用情况​

MLflow 会自动跟踪 OpenCode 对话中每次 LLM 调用的令牌使用情况。每次 LLM 调用的令牌使用情况都会记录在 mlflow.chat.tokenUsage 属性中。令牌使用情况和成本将显示在概览仪表板和追踪详情页面中。

OpenCode Trace Overview

会话和用户追踪​

该插件会自动为每个追踪记录跟踪会话和用户元数据

  • 会话 ID：每个 OpenCode 会话都标记有 mlflow.trace.session，允许你按会话对追踪记录进行分组和筛选。
  • 用户：当前系统用户标记有 mlflow.trace.user，可以轻松识别是谁发起了每次对话。
OpenCode Session Tracking

你可以使用这些元数据字段在 MLflow UI 中或通过搜索 API 筛选追踪记录。有关会话和用户追踪的更多详细信息，请参阅 跟踪用户和会话。

故障排除​

调试日志​

启用调试日志以查看有关追踪创建的详细信息

bash
export MLFLOW_OPENCODE_DEBUG=true
opencode

调试输出会被写入 stderr，以避免干扰 OpenCode 的 TUI（终端用户界面）。

常见问题​

未出现追踪记录

  1. 验证环境变量是否已正确设置

    bash
    echo $MLFLOW_TRACKING_URI
    echo $MLFLOW_EXPERIMENT_ID

  2. 检查 MLflow 服务器是否可访问

    bash
    curl $MLFLOW_TRACKING_URI/api/2.0/mlflow/experiments/list

  3. 启用调试日志以查看是否有任何错误

    bash
    export MLFLOW_OPENCODE_DEBUG=true

插件无法加载

  1. 验证插件是否已安装

    bash
    npm ls @mlflow/opencode

  2. 检查 opencode.json 是否包含该插件

    json
    {
      "plugin": ["@mlflow/opencode"]
    }

缺失令牌使用情况

令牌使用情况仅在 LLM 提供商报告时才可用。某些提供商或配置可能不会在其响应中包含令牌计数。

禁用追踪​

要停止自动追踪，请从 opencode.json 中移除该插件

json
{
  "plugin": []
}

或者取消设置环境变量

bash
unset MLFLOW_TRACKING_URI
unset MLFLOW_EXPERIMENT_ID

现有的追踪记录会被保留——禁用只会停止创建新的追踪记录。