Azure

Обзор

Azure — облачный провайдер, дающий доступ к моделям OpenAI и Anthropic через Azure OpenAI Service. Meridian берёт на себя следующие преобразования:

• Маппинг deployment'ов — идентификаторы моделей сопоставляются с Azure deployment ID, с учётом версий.
• Способы аутентификации — API-ключ, Entra ID (Service Principal) или Managed Identity (DefaultAzureCredential) с автоматическим определением окружения.
• Маршрутизация моделей — автоматическое определение базового провайдера (OpenAI vs Anthropic) по deployment'у.
• Версионирование API — настраиваемые версии API с поддержкой preview-версии для Responses API.
• Произвольный endpoint — полный контроль над URL Azure-ресурса.
• Несколько моделей — единый интерфейс для OpenAI, Anthropic (через Azure) и Gemini.
• Pass-through сырых тел — поддержка raw request/response для расширенных сценариев.

Поддерживаемые операции

Beta-заголовки

Для Anthropic-моделей в Azure Meridian валидирует заголовки anthropic-beta и удаляет неподдерживаемые. Azure поддерживает большинство beta-функций Anthropic.

Поддерживается: computer-use-*, structured-outputs-*, advanced-tool-use-*, mcp-client-*, prompt-caching-scope-*, compact-*, context-management-*, files-api-*, interleaved-thinking-*, skills-*, context-1m-*, redact-thinking-*.

Не поддерживается: fast-mode-*.

Поведение по умолчанию можно переопределить на уровне провайдера через вкладку Beta Headers в настройках провайдера или установив beta_header_overrides в network_config. Полная матрица поддержки — на странице Anthropic. Подробнее о настройке провайдеров — в Настройка провайдеров.

1. Chat Completions

Параметры запроса

Маппинг основных параметров

Конфигурация запроса

Azure использует произвольный endpoint и конфигурацию deployment'ов:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "azure/gpt-4-deployment",
    "messages": [{"role": "user", "content": "Hello"}],
    "deployment": "my-gpt4-deployment",
    "endpoint": "https://my-org.openai.azure.com"
  }' \
  -H "api-key: YOUR_AZURE_API_KEY"

Конфигурация ключа

Azure поддерживает три способа аутентификации: Managed Identity (DefaultAzureCredential), Entra ID (Service Principal) и Direct (API-ключ). Приоритет: Entra ID (если задан) → API-ключ (если задан value) → DefaultAzureCredential.

Managed Identity / DefaultAzureCredential

Если ни API-ключ, ни Entra ID-креды не заданы, Meridian автоматически использует DefaultAzureCredential, который сам определяет окружение аутентификации.

{
  "azure_key_config": {
    "endpoint": "https://your-org.openai.azure.com",
    "api_version": "2024-10-21",
    "deployments": {
      "gpt-4": "my-gpt4-deployment"
    }
  }
}

Azure Entra ID (Service Principal)

Если заданы client_id, client_secret и tenant_id, используется аутентификация Entra ID — она имеет приоритет над API-ключом.

{
  "azure_key_config": {
    "endpoint": "https://your-org.openai.azure.com",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "tenant_id": "your-tenant-id",
    "scopes": ["https://cognitiveservices.azure.com/.default"],
    "api_version": "2024-10-21",
    "deployments": {
      "gpt-4": "my-gpt4-deployment",
      "gpt-4-turbo": "my-gpt4-turbo-deployment",
      "claude-3": "my-claude-deployment"
    }
  }
}

Требуемые роли Azure:

• для OpenAI-моделей — Cognitive Services OpenAI User;
• для Anthropic-моделей — Cognitive Services AI Services User.

Direct Authentication (API-ключ)

{
  "azure_key_config": {
    "endpoint": "https://your-org.openai.azure.com",
    "api_version": "2024-10-21",
    "deployments": {
      "gpt-4": "my-gpt4-deployment",
      "gpt-4-turbo": "my-gpt4-turbo-deployment",
      "claude-3": "my-claude-deployment"
    }
  }
}

Параметры конфигурации:

• endpoint — endpoint Azure OpenAI ресурса (обязательный);
• client_id — client ID Azure Entra ID (опциональный, для Service Principal);
• client_secret — client secret Azure Entra ID (опциональный, для Service Principal);
• tenant_id — tenant ID Azure Entra ID (опциональный, для Service Principal);
• scopes — OAuth-области для запроса токена (по умолчанию ["https://cognitiveservices.azure.com/.default"]);
• api_version — версия API (по умолчанию 2024-10-21);
• deployments — соответствие имён моделей и deployment ID (опционально, можно переопределить в запросе);
• allowed_models — список моделей, разрешённых для этого ключа (опционально).

Выбор deployment'а

Deployment может задаваться на трёх уровнях (в порядке приоритета):

1. В запросе (наивысший приоритет):

   {"deployment": "custom-deployment"}

2. В конфигурации ключа:

   {"deployments": {"gpt-4": "my-gpt4-deployment"}}

3. По имени модели (низший приоритет, если deployment явно не указан): имя модели используется как deployment ID напрямую.

OpenAI-модели

При работе с OpenAI-моделями (GPT-4, GPT-4 Turbo, GPT-3.5-Turbo и т. п.) Meridian пробрасывает OpenAI-совместимые параметры напрямую.

Маппинг параметров для OpenAI

Все стандартные параметры OpenAI поддерживаются. Подробности — в разделе OpenAI.

Anthropic-модели

При работе с Anthropic-моделями через Azure (семейство Claude 3) Meridian преобразует запросы в формат Anthropic.

Маппинг параметров для Anthropic

Все стандартные параметры Anthropic поддерживаются с особой обработкой:

• Reasoning / thinking — параметры reasoning конвертируются в структуру thinking Anthropic.
• System-сообщения — изымаются из массива и помещаются в отдельное поле system.
• Группировка tool-сообщений — подряд идущие tool-сообщения объединяются.

Подробности — в разделе Anthropic.

Особенности Azure + Anthropic

• API-версия автоматически выставляется в 2023-06-01 для Anthropic-моделей.
• Внутри используются эндпоинты с префиксом /anthropic/v1/.
• Аутентификация для Anthropic-моделей — через заголовок x-api-key.
• Минимальный reasoning-бюджет — 1024 токена.

Версии API

• По умолчанию: 2024-10-21 (поддерживает актуальные возможности OpenAI).
• Preview: preview (используется для Responses API).
• Произвольная: через api_version в конфигурации ключа.

Разные версии API могут поддерживать разный набор фич. Meridian автоматически подстраивает пути эндпоинтов и параметры под выбранную версию.

Стриминг

Формат стриминга зависит от типа модели:

• OpenAI-модели — стандартный стриминг OpenAI с событиями chat.completion.chunk.
• Anthropic-модели — формат Anthropic с content-блоками.

2. Responses API

Responses API доступен и для OpenAI-, и для Anthropic-моделей через Azure и использует preview-версию API.

Параметры запроса

Маппинг основных параметров

OpenAI-модели

Для OpenAI-моделей (GPT-4 и т. п.) применяется конвертация формата OpenAI Responses API.

Anthropic-модели

Для Anthropic-моделей (Claude и т. п.) применяется конвертация формата сообщений Anthropic:

• instructions становится system-сообщением;
• reasoning маппится в структуру thinking.

Конфигурация запроса

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "azure/claude-3-sonnet",
    "input": "Hello, how are you?",
    "instructions": "You are a helpful assistant",
    "deployment": "my-claude-deployment",
    "endpoint": "https://my-org.openai.azure.com"
  }' \
  -H "api-key: YOUR_AZURE_API_KEY"

Особенности обработки

• Используется эндпоинт /openai/v1/responses с preview-версией API.
• Все конвертации тела запроса выполняются автоматически.
• Поддерживается raw-passthrough тела запроса для расширенных сценариев.

OpenAI-модели — особая обработка gpt-oss. Подробности о различиях обработки reasoning между gpt-oss и остальными моделями — на странице OpenAI → Responses API.

Anthropic-модели: параметры — на странице Anthropic → Responses API.

3. Embeddings

Embeddings поддерживаются только для OpenAI-моделей (для Anthropic в Azure embeddings недоступны).

Параметры запроса

curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["text to embed"],
    "deployment": "my-embedding-deployment"
  }' \
  -H "api-key: YOUR_AZURE_API_KEY"

Конверсия ответа

Embeddings-ответ пробрасывается напрямую от Azure OpenAI в стандартном формате:

{
  "data": [
    {
      "object": "embedding",
      "embedding": [0.1234, -0.5678],
      "index": 0
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

4. Files API

Files API поддерживается только для OpenAI-моделей.

Поддерживаемые операции

Файлы хранятся в Azure и могут использоваться в batch-операциях.

5. Image Generation

Image Generation поддерживается для OpenAI-моделей в Azure и использует OpenAI-совместимый формат.

Параметры запроса

Маппинг основных параметров

Azure использует ту же конвертацию, что и OpenAI (см. OpenAI → Image Generation):

• Model и Prompt: bifrostReq.Model → req.Model (мап на deployment), bifrostReq.Prompt → req.Prompt.
• Параметры: все остальные поля из bifrostReq встраиваются непосредственно в OpenAI-структуру через struct embedding.

Конфигурация запроса

curl -X POST http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "azure/dall-e-3",
    "prompt": "A sunset over the mountains",
    "size": "1024x1024",
    "n": 1,
    "deployment": "my-image-gen-deployment"
  }' \
  -H "api-key: YOUR_AZURE_API_KEY"

Конверсия ответа

• Без стриминга. Azure-ответы анмаршалятся напрямую в BifrostImageGenerationResponse — схема Meridian является надмножеством формата OpenAI.
• Стриминг. Azure-стриминг — Server-Sent Events с теми же типами событий, что и в OpenAI (см. OpenAI → Image Generation).

Стриминг

Стриминг для image generation поддерживается и использует формат OpenAI Server-Sent Events.

6. Image Edit

Image Edit поддерживается для OpenAI-моделей в Azure и использует OpenAI-совместимый формат.

Конвертация — та же, что у OpenAI (см. OpenAI → Image Edit):

• Конвертация запроса выполняется через openai.HandleOpenAIImageEditRequest с азурной сборкой URL.
• Формат URL: {endpoint}/openai/deployments/{deployment}/images/edits?api-version={apiVersion}.
• Аутентификация — Azure API-ключ или OAuth bearer-токен (через getAzureAuthHeaders).
• Маппинг deployment'а — идентификатор модели транслируется в Azure deployment ID.
• Конверсия ответа — как в OpenAI: ответы анмаршалятся в BifrostImageGenerationResponse.
• Стриминг — поддерживается через openai.HandleOpenAIImageEditStreamRequest с азурной сборкой URL и аутентификацией.

Эндпоинт: /openai/deployments/{deployment}/images/edits?api-version={apiVersion}.

7. List Models

Параметры запроса

Не требуются.

Конверсия ответа

Возвращается список моделей и deployment'ов, сконфигурированных в ключе Azure. Ответ включает метаданные модели, capabilities и lifecycle-статус.

{
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1687882411,
      "status": "active",
      "lifecycle_status": "stable",
      "capabilities": {
        "chat_completion": true,
        "embeddings": false
      }
    }
  ]
}

8. Video Generation

Azure маршрутизирует video generation в модели Sora через OpenAI-совместимый Azure-эндпоинт. Параметры идентичны OpenAI → Video Generation.

Поддерживаемые операции

Нюансы реализации

Конфигурация

HTTP-настройки: API Version 2024-10-21 (настраиваемая) | Max Connections 5000 | Max Idle 60 секунд.

Формат эндпоинта: https://{resource-name}.openai.azure.com/openai/v1/{path}?api-version={version}.

Meridian автоматически собирает URL по endpoint'у из конфигурации ключа и заданной версии API.

Установка и настройка

Azure требует endpoint URL, маппингов deployment'ов и версии API. Подробные инструкции по аутентификации в Azure — на странице Настройка провайдеров.