Consulta a proveedores de modelos externos (servicios de proveedores de modelo)

Consulta a un proveedor de modelos externo (servicio de proveedor modelo) a través de Unity AI Gateway, que proporciona las credenciales almacenadas y enruta la solicitud al proveedor externo, para que los llamantes no gestionen el secreto del proveedor.

Requirements

• Permiso del espacio de trabajo para realizar consultas: Acceso al espacio de trabajo, o Acceso del consumidor con la versión preliminar de Acceso del consumidor a Unity AI Gateway habilitada para tu cuenta (Versión preliminar pública). Consulta Administrar derechos y Administrar las versiones preliminares de Azure Databricks.
• Se necesitan los permisos siguientes. Consulta Descubrir y gestionar el acceso a proveedores de modelos externos (servicios de proveedores de modelos).
  • EXECUTE en el servicio del proveedor de modelos
  • USE CATALOG en el catálogo
  • USE SCHEMA en el esquema

Identificación de un servicio de proveedor de modelos

Se selecciona un servicio proveedor de modelos para una solicitud con el encabezado Databricks-Model-Provider-Service, configurado con el nombre de tres partes del servicio:

Databricks-Model-Provider-Service: main.default.openai_prod

Autentíquese con el token de Azure Databricks, no con la credencial del proveedor. La dirección URL base es la dirección URL del área de trabajo seguida de /ai-gateway.

Consultar las API admitidas

Las rutas de acceso administradas hacen que la API de cada proveedor esté disponible en una ruta de acceso estable de Unity AI Gateway. Unity AI Gateway se traduce entre la solicitud y el proveedor, aplica la gobernanza, como límites de protección y límites de velocidad, y registra el uso. Esta es la manera recomendada de consultar un servicio de proveedor de modelos.

En el ejemplo siguiente se envía una respuesta de chat a través de un servicio proveedor de modelos de OpenAI mediante la ruta administrada de OpenAI. Dado que la solicitud utiliza la API de Chat Completions de OpenAI, puede configurar el cliente de OpenAI para que use la URL base de Unity AI Gateway.

Python

from openai import OpenAI

client = OpenAI(
    api_key="<databricks-token>",
    base_url="https://<workspace-url>/ai-gateway/openai/v1",
    default_headers={"Databricks-Model-Provider-Service": "main.default.openai_prod"},
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in exactly 3 words."}],
)
print(response.choices[0].message.content)

REST

curl https://<workspace-url>/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in exactly 3 words."}]
  }'

La ruta administrada que invoca depende de la API del proveedor:

El modelo en el cuerpo de la solicitud (o en el segmento de ruta de Gemini) debe ser uno que el servicio proveedor de modelos permita.

Consulta de otras API (paso a través)

Si una ruta gestionada no cubre un endpoint del proveedor, como un archivo OpenAI o un endpoint batch, puedes pasar la solicitud al proveedor sin cambios. Unity AI Gateway quita el /ai-gateway prefijo, adjunta la credencial almacenada y reenvía la ruta de acceso restante al proveedor.

Para habilitar el acceso directo no administrado, seleccione Reenviar todas las rutas de acceso url en Opciones avanzadas al crear o actualizar el servicio de proveedor de modelos en la interfaz de usuario.

Después de habilitar paso directivo, llame a la ruta nativa del proveedor en /ai-gateway. Por ejemplo, listar archivos en el endpoint de archivos de OpenAI:

curl https://<workspace-url>/ai-gateway/files \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod"

Reenvío de encabezados y parámetros de consulta

De forma predeterminada, Unity AI Gateway no pasa los encabezados de solicitud ni los parámetros de consulta del cliente al proveedor ascendente. Dos marcas de configuración de servicio cambian esto y se aplican a rutas de acceso administradas y no administradas:

• forward_headers: Cuando true, Unity AI Gateway reenvía las cabeceras de solicitud del cliente al proveedor. Habilite esto cuando un proveedor requiera un encabezado que Unity AI Gateway no establezca para usted, como OpenAI-Organization.
• forward_query_parameters: Cuando true, Unity AI Gateway reenvía los parámetros de consulta del cliente al proveedor.

Establézcalos en el servicio de proveedor de modelos como cualquier otro campo de configuración:

curl https://<workspace-url>/api/2.1/unity-catalog/model-provider-services/main.default.openai_prod \
  -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -G \
  --data-urlencode "update_mask=config.forward_headers,config.forward_query_parameters" \
  --data '{ "config": { "forward_headers": true, "forward_query_parameters": true } }'

Solicitudes de etiquetas para el seguimiento de uso

Puede adjuntar etiquetas de clave-valor personalizadas a solicitudes individuales mediante el Databricks-Ai-Gateway-Request-Tags encabezado HTTP. Unity AI Gateway registra las etiquetas de las solicitudes en la columna request_tags tanto de la tabla del sistema de seguimiento de uso como de las tablas de inferencia. Después, puede realizar un seguimiento de los costos, el uso de atributos y el análisis de filtros por proyecto, equipo, entorno u otra dimensión.

El valor del encabezado debe ser un objeto JSON que asigna claves de cadena a valores de cadena. Por ejemplo:

{ "project": "chatbot", "team": "ml-platform", "environment": "production" }

Envíe el encabezado de etiquetas junto con el encabezado Databricks-Model-Provider-Service. Use el extra_headers parámetro (Python) o pase el encabezado directamente (API REST):

Python

from openai import OpenAI
import json

client = OpenAI(
    api_key="<databricks-token>",
    base_url="https://<workspace-url>/ai-gateway/openai/v1",
    default_headers={"Databricks-Model-Provider-Service": "main.default.openai_prod"},
)

request_tags = {"project": "chatbot", "team": "ml-platform"}

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "What is Databricks?"}],
    extra_headers={"Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags)},
)

REST

curl https://<workspace-url>/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod" \
  -H "Content-Type: application/json" \
  -H 'Databricks-Ai-Gateway-Request-Tags: {"project": "chatbot", "team": "ml-platform"}' \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "What is Databricks?"}]
  }'

Pasos siguientes

• Descubre y regula el acceso a proveedores modelo externos (servicios de proveedores modelo)
• Uso del modelo de vía
• Administrar proveedores externos de modelos (servicios de proveedores de modelos)