与编码代理集成

重要

此功能在 Beta 版中。帐户管理员可以从帐户控制台预览页控制对此功能的访问。请参阅 Manage Azure Databricks 预览版。

使用Azure Databricks编码代理集成，可以管理对 Cursor、Gemini CLI 和 Codex CLI 等编码代理的访问和使用。它基于 Unity AI 网关构建，为编码工具提供速率限制、使用情况跟踪和推理表。

Features

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

要求

已为您的账户启用 Unity AI 网关预览版。请参阅 Manage Azure Databricks 预览版。
Unity AI 网关支持的区域中的Azure Databricks工作区。
为工作区启用 Unity 目录。请参阅为 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 函数、向量搜索、SQL 仓库以及已发现的外部连接）注册到支持 MCP 的代理中：

ucode configure mcp

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

ucode usage

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

ucode --help

仪表盘

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

若要打开仪表板，请从“AI 网关”页中选择“ 查看仪表板 ”。此操作创建一个预配置的仪表板，其中包含用于编码工具用法的图形。

“查看仪表板”按钮

编码代理仪表板

手动设置

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

Cursor IDE
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：添加自定义模型

在游标设置中单击“ + 添加自定义模型 ”。
添加 Unity AI 网关端点名称并启用开关。

注释

目前，仅支持由 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> 替换为个人访问令牌。

设置 OpenTelemetry 数据收集

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

要求

已在 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-05-30