Integracja z agentami kodowania

Ważna

Ta funkcja jest dostępna w wersji beta. Administratorzy kont mogą kontrolować dostęp do tej funkcji ze strony podglądów konsoli konta. Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Dzięki integracji z agentem kodowania Azure Databricks możesz kierować ruch od agentów kodowania, takich jak Cursor, Gemini CLI i Codex CLI, za pośrednictwem usług modeli w Unity AI Gateway. Zapewnia to ograniczanie szybkości, śledzenie użycia i tabele wnioskowania — ze wszystkimi kontrolkami skonfigurowanymi na poziomie usługi modelu, użytkownika lub grupy.

Features

• Dostęp: bezpośredni dostęp do różnych narzędzi i modeli kodowania, a wszystko w ramach jednej faktury.
• Możliwość obserwowania: jeden ujednolicony pulpit nawigacyjny do śledzenia użycia, wydatków i metryk we wszystkich narzędziach do kodowania.
• Ujednolicone zarządzanie: Administratorzy mogą zarządzać uprawnieniami modeli i limitami liczby żądań za pośrednictwem usługi Unity AI Gateway na poziomie usługi modelu, użytkownika lub grupy.

Requirements

• Usługa Unity AI Gateway w wersji zapoznawczej jest włączona dla twojego konta. Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.
• Obszar roboczy Azure Databricks w regionie obsługiwanym przez Unity AI Gateway.
• Katalog Unity włączony dla obszaru roboczego. Zobacz Umożliwienie obszaru roboczego dla Unity Catalog.

Konfiguracja

Najszybszym sposobem rozpoczęcia pracy jest ucode, interfejs wiersza polecenia z Azure Databricks, który instaluje, uwierzytelnia i konfiguruje obsługiwanych agentów kodowania za pomocą usługi Unity AI Gateway w jednym poleceniu.

Użyj kodu ucode (zalecane)

ucode (interfejs wiersza poleceń do kodowania Unity AI Gateway) to jeden punkt dostępu do uruchamiania agentów kodujących za pośrednictwem Unity AI Gateway. Obsługuje protokół OAuth, zapisuje plik konfiguracji każdego agenta i kieruje ruch przez dowolny zarejestrowany serwer LLM lub MCP. Obsługiwani agenci:

• Codex — Interfejs wiersza polecenia
• Gemini CLI
• OpenCode
• GitHub Copilot CLI
• Pi
• i wiele więcej

Krok 1. Instalowanie kodu ucode

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

Wymaga Pythona 3.12 lub nowszego i uv.

Krok 2. Otwieranie agenta kodowania

Uruchom żądanego agenta. Podczas pierwszego uruchamiania ucode monituje o adres URL obszaru roboczego Azure Databricks, uwierzytelnia się i automatycznie zapisuje plik konfiguracji agenta. Kolejne uruchomienia są kierowane bezpośrednio do agenta.

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

ucode przekazuje flagi umieszczone po nazwie agenta do narzędzia bazowego, na przykład:

ucode codex --full-auto

Aby skonfigurować wielu agentów kodowania w tym samym czasie, uruchom polecenie:

ucode configure

Aby zarejestrować serwery MCP usługi Azure Databricks (funkcje Unity Catalog, AI Search, magazyny SQL oraz wykryte połączenia zewnętrzne) w agentach obsługujących MCP:

ucode configure mcp

Aby wyświetlić podsumowanie użycia usługi Unity AI Gateway z ostatnich 7 dni:

ucode usage

Aby wyświetlić pełny opis poleceń, uruchom:

ucode --help

Dashboard

Gdy użycie agenta programistycznego jest śledzone za pośrednictwem Unity AI Gateway, możesz wyświetlać swoje metryki i monitorować je we wbudowanym panelu.

Aby otworzyć panel, kliknij Govern w prawym górnym rogu strony Unity AI Gateway, a następnie kliknij Usage Dashboard. Wbudowany panel użycia zawiera kartę Agenty kodujące z wykresami przedstawiającymi użycie narzędzi do kodowania.

Konfiguracja ręczna

Jeśli wolisz skonfigurować agentów samodzielnie, postępuj zgodnie z instrukcjami dotyczącymi:

• IDE Cursor
• Codex — Interfejs wiersza polecenia
• Gemini CLI

IDE Cursor

Aby skonfigurować Cursor do korzystania z usług modeli w usłudze Unity AI Gateway:

Krok 1. Konfigurowanie podstawowego adresu URL i klucza interfejsu API

1. Otwórz kursor i przejdź do Ustawienia>Ustawienia kursora>Modele>Klucze API.

2. Włącz zastąpienie podstawowego adresu URL OpenAI i wprowadź adres URL:

   https://<workspace-url>/ai-gateway/cursor/v1
   

   Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks.

3. Wklej osobisty token dostępu Azure Databricks do pola OpenAI API Key.

Krok 2. Dodawanie modeli niestandardowych

1. Kliknij + Dodaj model niestandardowy w ustawieniach kursora.
2. Dodaj nazwę usługi modelowej (na przykład system.ai.databricks-claude-opus-4-6) i włącz przełącznik.

Note

Obecnie obsługiwane są tylko usługi modelu udostępniane Azure Databricks.

Krok 3. Testowanie integracji

1. Otwórz tryb zapytaj przy użyciu Cmd+L (macOS) lub Ctrl+L (Windows/Linux) i wybierz model.
2. Wyślij wiadomość. Wszystkie żądania są teraz kierowane przez usługę Azure Databricks.

Interfejs wiersza polecenia Codex

Krok 1. Instalowanie lub aktualizowanie interfejsu wiersza polecenia Codex

Zainstaluj lub zaktualizuj interfejs wiersza polecenia Codex w wersji 0.118 lub nowszej:

npm install -g @openai/codex@latest

Krok 2. Tworzenie lub aktualizowanie pliku konfiguracji Codex

Utwórz lub edytuj plik konfiguracji Codex pod adresem ~/.codex/config.toml:

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

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks.

Krok 3. Uwierzytelnianie w obszarze roboczym

Note

Należy to zrobić tylko raz. Nie trzeba ponownie uwierzytelniać się za każdym razem, gdy uruchamiasz Codex.

Najpierw upewnij się, że masz zainstalowany Azure Databricks CLI. Aby uzyskać instrukcje, zobacz Instalowanie lub aktualizowanie interfejsu wiersza polecenia usługi Databricks .

Następnie uwierzytelnij:

databricks auth login --host <workspace-url>

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks.

Krok 4. Uruchamianie kodu

codex

Aby zmienić model, użyj polecenia /model.

Gemini CLI

Krok 1. Instalowanie najnowszej wersji interfejsu wiersza polecenia Gemini

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

Krok 2. Konfigurowanie zmiennych środowiskowych

Utwórz plik ~/.gemini/.env i dodaj następującą konfigurację. Aby uzyskać więcej informacji, zobacz dokumentację uwierzytelniania interfejsu wiersza polecenia Gemini .

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>

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks i <databricks_pat_token> osobistym tokenem dostępu.

Używaj modeli open source z agentami programistycznymi

Azure Databricks wspiera integrację modeli open source (OSS), takich jak glm-5-2, z agentami kodującymi.

Oprócz powyższych wymagań , twoja przestrzeń pracy musi mieć również dostęp do docelowego modelu OSS.

OpenCode

Ustaw ucode zgodnie z opisem w Use ucode (zalecane), a następnie wybierz system.ai.glm-5-2 jako swój model.

Ręczna konfiguracja

Alternatywnie możesz zainstalować OpenCode zgodnie z dokumentacją OpenCode, a następnie utworzyć lub edytować ~/.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>": {}
      }
    }
  }
}

Zastąp następujące elementy:

• <workspace-url> przy użyciu adresu URL obszaru roboczego usługi Azure Databricks.
• <databricks_pat_token> przy użyciu osobistego tokenu dostępu.
• <open source model service name> z docelową usługą modelową OSS, na przykład system.ai.glm-5-2.

Następnie zacznij OpenCode:

opencode

Kodeks

Codex łączy się z modelami open source poprzez API Open Responses , które Codex obsługuje.

Skonfiguruj ucode zgodnie z opisem w Użyj ucode (zalecane), a następnie uruchom:

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

Na przykład, aby użyć GLM 5.2 z Codexem, wykonaj:

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

Ręczna konfiguracja

Alternatywnie możesz zainstalować Codex CLI zgodnie z opisem w Codex CLI, a następnie utworzyć lub edytować ~/.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

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks, a <open source model service name> docelową usługą modelu OSS, na przykład system.ai.glm-5-2.

Następnie uruchom Codex:

codex

Konfigurowanie zbierania danych OpenTelemetry

Azure Databricks obsługuje eksportowanie metryk i logów OpenTelemetry z agentów kodowania do zarządzanych przez Unity Catalog tabel Delta. Wszystkie metryki to dane szeregów czasowych eksportowane przy użyciu standardowego protokołu metryk OpenTelemetry, a dzienniki są eksportowane przy użyciu protokołu dzienników OpenTelemetry.

Requirements

• Usługa OpenTelemetry w wersji zapoznawczej usługi Azure Databricks jest włączona. Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Krok 1: Tworzenie tabel OpenTelemetry w Unity Catalog

Utwórz prekonfigurowane tabele zarządzane Unity Catalog za pomocą schematów metryk i dzienników OpenTelemetry.

Tabela metryk

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'
)

Tabela dzienników

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'
)

Krok 2. Aktualizowanie wariantów env w agencie kodowania

W przypadku dowolnego agenta kodowania z włączoną obsługą metryk OpenTelemetry skonfiguruj następujące zmienne środowiskowe.

{
  "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"
}

Krok 3. Uruchamianie agenta kodowania.

Dane powinny trafić do tabel katalogu Unity w ciągu 5 minut.

Następne kroki

• Usługi modelu
• Tworzenie usług modelu i zarządzanie nimi
• Usługi modelu zapytań
• Odkrywanie i zarządzanie dostępem do usług modelowych