与编码代理集成

借助Azure Databricks编码代理集成，可以通过 Unity AI 网关中的模型服务路由来自编码代理（如 Cursor、Gemini CLI 和 Codex CLI）的流量。这提供了速率限制、使用情况跟踪和推理表，并在模型服务、用户或组级别配置了所有控件。

Features

访问：直接访问各种编码工具和模型，全部在一张发票下。
可观测性：用于跟踪所有编码工具中的使用情况、支出和指标的单个统一仪表板。
统一治理：管理员可以在模型服务、用户或组级别通过 Unity AI 网关管理模型权限和速率限制。

Requirements

Unity AI 网关支持的区域中的Azure Databricks工作区。
你的工作区已启用 Unity Catalog。请参阅为工作区启用 Unity Catalog。

Setup

最快的入门方式是使用来自 Azure Databricks 的 CLI 工具 ucode，只需一条命令即可为受支持的编码代理完成安装、身份验证以及 Unity AI Gateway 配置。

使用 ucode （建议）

ucode （Unity AI 网关编码 CLI）是针对 Unity AI 网关运行编码代理的单个入口点。它处理 OAuth、写入每个代理的配置文件，并通过已注册的任何 LLM 或 MCP 服务器路由流量。支持的代理：

步骤 1：安装 ucode

uv tool install git+https://github.com/databricks/ucode

需要 Python 3.12 或更高版本和 uv。

步骤 2：打开编码代理

运行你想要的代理。首次启动时，ucode提示输入Azure Databricks工作区 URL、进行身份验证并自动写入代理的配置文件。随后的启动将直接转到智能体。

ucode codex      # OpenAI Codex
ucode gemini     # Gemini CLI
ucode opencode   # OpenCode
ucode copilot    # GitHub Copilot CLI
ucode pi         # Pi

ucode 将代理名称之后的标志传递到基础工具，例如：

ucode codex --full-auto

若要同时配置多个编码代理，请运行：

ucode configure

若要将 Azure Databricks MCP 服务器（Unity Catalog 函数、AI 搜索、SQL 仓库和已发现的外部连接）注册到支持 MCP 的代理中：

ucode configure mcp

若要查看过去 7 天的 Unity AI 网关使用情况摘要，请执行以下操作：

ucode usage

对于完整的命令引用，请运行：

ucode --help

Dashboard

通过 Unity AI 网关跟踪编码代理使用情况后，可以在内置仪表板中查看和监视指标。

若要打开仪表板，请单击 Unity AI 网关页面右上角的 “治理 ”，然后单击“ 使用情况仪表板”。内置使用情况仪表板设有 编码代理 选项卡，其中包含显示编码工具使用情况的图表。

编码代理仪表板

手动安装

如果希望自己配置代理，请按照以下说明操作：

光标集成开发环境
Codex CLI
Gemini CLI

游标 IDE

若要将 Cursor 配置为在 Unity AI 网关中使用模型服务，请执行以下操作：

步骤 1：配置基本 URL 和 API 密钥

打开光标并导航到 “设置>游标设置”>模型>API 密钥。
启用替代 OpenAI 基础 URL，并输入 URL：
```
https://<workspace-url>/ai-gateway/cursor/v1
```
将 <workspace-url> 替换为Azure Databricks工作区 URL。
将 Azure Databricks 个人访问令牌粘贴到 OpenAI API 密钥 字段中。

步骤 2：添加自定义模型

在游标设置中单击“ + 添加自定义模型 ”。
添加模型服务名称（例如）， system.ai.databricks-claude-opus-4-6并启用切换。

注释

目前，仅支持Azure Databricks提供的模型服务。

步骤 3：测试集成

使用 Cmd+L （macOS）或 Ctrl+L （Windows/Linux）打开 Ask 模式，然后选择模型。
发送消息。所有请求现在都通过 Azure Databricks 进行路由。

Codex 命令行界面 (Codex CLI)

步骤 1：安装或更新 Codex CLI

安装或更新 Codex CLI 版本 0.118 或更高版本：

npm install -g @openai/codex@latest

步骤 2：创建或更新 Codex 配置文件

在 ~/.codex/config.toml 处创建或编辑 Codex 配置文件。

profile = "default"

[profiles.default]
model_provider = "Databricks"

[model_providers.Databricks]
name = "Databricks :re[ai-gateway]"
base_url = "<workspace-url>/ai-gateway/codex/v1"
wire_api = "responses"

[model_providers.Databricks.auth]
command = "sh"
args = ["-c", "databricks auth token --host <workspace-url> --output json | jq -r '.access_token'"]
timeout_ms = 5000
refresh_interval_ms = 1800000

将 <workspace-url> 替换为Azure Databricks工作区 URL。

步骤 3：向工作区进行身份验证

注释

此操作仅需执行一次。每次启动 Codex 时，无需重新进行身份验证。

首先，请确保已安装 Azure Databricks CLI。请参阅安装或更新 Databricks CLI 以获取说明。

然后进行身份验证：

databricks auth login --host <workspace-url>

将 <workspace-url> 替换为Azure Databricks工作区 URL。

步骤 4：启动 Codex

codex

若要更改模型，请使用 /model。

Gemini CLI

步骤 1：安装 Gemini CLI 的最新版本

npm install -g @google/gemini-cli@nightly

步骤 2：配置环境变量

创建文件 ~/.gemini/.env 并添加以下配置。有关更多详细信息，请参阅 Gemini CLI 身份验证文档。

GEMINI_MODEL=databricks-gemini-2-5-flash
GOOGLE_GEMINI_BASE_URL=https://<workspace-url>/ai-gateway/gemini
GEMINI_API_KEY_AUTH_MECHANISM="bearer"
GEMINI_API_KEY=<databricks_pat_token>

将 <workspace-url> 替换为Azure Databricks工作区 URL，并将 <databricks_pat_token> 替换为个人访问令牌。

使用带有编码代理的开源模型

Azure Databricks 支持将开放源代码（OSS）模型（如 glm-5-2）与编码代理集成。

除了上述要求外，你的工作区还必须能够访问目标OSS模型。

OpenCode

按照ucode中的说明设置，然后选择system.ai.glm-5-2作为你的模型。

手动设置

或者，您也可以按照 OpenCode文档中描述安装OpenCode，然后创建或编辑 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "databricks-oss/<open source model service name>",
  "provider": {
    "databricks-oss": {
      "npm": "@ai-sdk/openai",
      "options": {
        "baseURL": "<workspace-url>/ai-gateway/mlflow/v1",
        "apiKey": "<databricks_pat_token>"
      },
      "models": {
        "<open source model service name>": {}
      }
    }
  }
}

替换以下内容：

<workspace-url> 使用 Azure Databricks 工作区 URL。
<databricks_pat_token> 使用个人访问令牌。
<开放源代码 model service name> 与目标 OSS 模型服务（例如 system.ai.glm-5-2）一起使用。

然后开始OpenCode：

opencode

法典

Codex 通过 Codex 支持的开放响应 API 连接到开源模型。

按照ucode中所述设置，然后运行：

ucode codex --model <open source model service name>

例如，要在Codex中使用GLM 5.2，运行：

ucode codex --model system.ai.glm-5-2

手动设置

或者，您也可以按照 Codex CLI中描述安装Codex CLI，然后创建或编辑 ~/.codex/config.toml：

model = "<open source model service name>"
model_provider = "Databricks"

[model_providers.Databricks]
name = "Databricks :re[ai-gateway]"
base_url = "<workspace-url>/ai-gateway/codex/v1"
wire_api = "responses"

[model_providers.Databricks.auth]
command = "sh"
args = ["-c", "databricks auth token --host <workspace-url> --output json | jq -r '.access_token'"]
# Re-run the token command periodically so long sessions don't fail when the
# short-lived Databricks token expires.
timeout_ms = 5000
refresh_interval_ms = 1800000

将 <workspace-url> 替换为你的 Azure Databricks 工作区 URL，并将 <开放源代码 model service name> 替换为目标 OSS 模型服务，例如 system.ai.glm-5-2。

然后启动 Codex：

codex

配置 OpenTelemetry 数据收集

Azure Databricks 支持将 OpenTelemetry 指标和日志从编码代理导出到 Unity 目录托管 Delta 表。所有指标都是使用 OpenTelemetry 标准指标协议导出的时序数据，并使用 OpenTelemetry 日志协议导出日志。

Requirements

已在 Azure Databricks 预览版上启用 OpenTelemetry。请参阅 Manage Azure Databricks 预览版。

步骤 1：在 Unity 目录中创建 OpenTelemetry 表

创建已根据 OpenTelemetry 指标和日志架构预配置的 Unity Catalog 管理表。

指标表

CREATE TABLE <catalog>.<schema>.<table_prefix>_otel_metrics (
  name STRING,
  description STRING,
  unit STRING,
  metric_type STRING,
  gauge STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT
  >,
  sum STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT,
    aggregation_temporality: STRING,
    is_monotonic: BOOLEAN
  >,
  histogram STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    bucket_counts: ARRAY<LONG>,
    explicit_bounds: ARRAY<DOUBLE>,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT,
    min: DOUBLE,
    max: DOUBLE,
    aggregation_temporality: STRING
  >,
  exponential_histogram STRUCT<
    attributes: MAP<STRING, STRING>,
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    scale: INT,
    zero_count: LONG,
    positive_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    negative_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    flags: INT,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    min: DOUBLE,
    max: DOUBLE,
    zero_threshold: DOUBLE,
    aggregation_temporality: STRING
  >,
  summary STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    quantile_values: ARRAY<STRUCT<
      quantile: DOUBLE,
      value: DOUBLE
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT
  >,
  metadata MAP<STRING, STRING>,
  resource STRUCT<
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  metric_schema_url STRING
) USING DELTA
TBLPROPERTIES (
  'otel.schemaVersion' = 'v1'
)

日志表

CREATE TABLE <catalog>.<schema>.<table_prefix>_otel_logs (
  event_name STRING,
  trace_id STRING,
  span_id STRING,
  time_unix_nano LONG,
  observed_time_unix_nano LONG,
  severity_number STRING,
  severity_text STRING,
  body STRING,
  attributes MAP<STRING, STRING>,
  dropped_attributes_count INT,
  flags INT,
  resource STRUCT<
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  log_schema_url STRING
) USING DELTA
TBLPROPERTIES (
  'otel.schemaVersion' = 'v1'
)

步骤 2：在代码代理中更新环境变量

在启用了 OpenTelemetry 指标支持的任何编码代理中，配置以下环境变量。

{
  "OTEL_METRICS_EXPORTER": "otlp",
  "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://<workspace-url>/api/2.0/otel/v1/metrics",
  "OTEL_EXPORTER_OTLP_METRICS_HEADERS": "content-type=application/x-protobuf,Authorization=Bearer <databricks_pat_token>,X-Databricks-UC-Table-Name=<catalog>.<schema>.<table_prefix>_otel_metrics",
  "OTEL_METRIC_EXPORT_INTERVAL": "10000",
  "OTEL_LOGS_EXPORTER": "otlp",
  "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://<workspace-url>/api/2.0/otel/v1/logs",
  "OTEL_EXPORTER_OTLP_LOGS_HEADERS": "content-type=application/x-protobuf,Authorization=Bearer <databricks_pat_token>,X-Databricks-UC-Table-Name=<catalog>.<schema>.<table_prefix>_otel_logs",
  "OTEL_LOGS_EXPORT_INTERVAL": "5000"
}

步骤 3：运行编码代理。

数据应在 5 分钟内传播到 Unity 目录表。

后续步骤

反馈

此页面是否有帮助？

Last updated on 2026-08-05

与编码代理集成

Features

Requirements

Setup

使用 ucode （建议）

Dashboard

手动安装

游标 IDE

Codex 命令行界面 (Codex CLI)

Gemini CLI

使用带有编码代理的开源模型

OpenCode

法典

配置 OpenTelemetry 数据收集

Requirements

步骤 1：在 Unity 目录中创建 OpenTelemetry 表

步骤 2：在代码代理中更新环境变量

步骤 3：运行编码代理。

后续步骤

反馈

其他资源