Anthropic

Обзор

Формат Anthropic существенно отличается от OpenAI. Meridian берёт на себя обширное преобразование:

• Извлечение system-сообщений — изымаются из массива messages и помещаются в отдельное поле system.
• Группировка tool-сообщений — несколько подряд идущих tool-сообщений объединяются в одно user-сообщение.
• Преобразование thinking-блоков — параметры reasoning мапятся в структуру thinking Anthropic.
• Переименование параметров — например, max_completion_tokens → max_tokens, stop → stop_sequences.
• Преобразование контента — изображения, файлы и другие типы контента приводятся к схеме Anthropic.

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

Beta-заголовки

Meridian автоматически управляет beta-заголовками Anthropic — определяет необходимые заголовки по фичам в запросе и инжектит их. Заголовки валидируются для каждого провайдера, чтобы неподдерживаемые заголовки не уходили в апстрим.

1. Chat Completions

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

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

Игнорируемые параметры

Следующие параметры тихо игнорируются: frequency_penalty, presence_penalty, logit_bias, logprobs, top_logprobs, seed, parallel_tool_calls, service_tier.

Дополнительные параметры

Используйте extra_params (SDK) или передавайте напрямую в теле запроса (Gateway) для полей, специфичных для Anthropic:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-5-sonnet",
    "messages": [{"role": "user", "content": "Hello"}],
    "top_k": 40
  }'

Anthropic также принимает на верхнем уровне объект "cache_control": {"type": "ephemeral"} в запросах к /anthropic/v1/messages — это включает автоматическое prompt caching. Meridian пробрасывает директиву без изменений.

Cache control

Cache-директивы можно добавлять в system-сообщения, user-сообщения и определения инструментов, чтобы включить prompt caching:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-5-sonnet",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "This is cached context",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      }
    ],
    "system": [
      {
        "type": "text",
        "text": "You are a helpful assistant",
        "cache_control": {"type": "ephemeral"}
      }
    ]
  }'

Reasoning / Thinking

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

• reasoning.effort → thinking.type (всегда "enabled").
• reasoning.max_tokens → thinking.budget_tokens (бюджет токенов на thinking).

Критичные ограничения

• Минимальный бюджет: требуется не менее 1024 токенов; при меньшем значении запрос отклоняется с ошибкой.
• Динамический бюджет: значение -1 автоматически приводится к 1024.

Пример

// Запрос
{"reasoning": {"effort": "high", "max_tokens": 2048}}

// Преобразование для Anthropic
{"thinking": {"type": "enabled", "budget_tokens": 2048}}

Преобразование сообщений

Критичные нюансы

• Извлечение system-сообщений. System-сообщения изымаются из массива и помещаются в отдельное поле system. Несколько system-сообщений становятся отдельными text-блоками в массиве system.
• Группировка tool-сообщений. Подряд идущие tool-сообщения объединяются в одно user-сообщение с блоками tool_result.

Преобразование изображений

• Изображения по URL: {"type": "image_url", "image_url": {}} → {"type": "image", "source": {"type": "url", ...}}.
• Изображения в base64: data URL → {"type": "image", "source": {"type": "base64", "media_type": "image/png", ...}}.

Где допустим cache control

Cache-директивы поддерживаются в: блоках content для system, блоках content для user-сообщений, определениях инструментов (примеры — в разделе Cache control выше).

Преобразование инструментов

Определения инструментов реструктурируются: function.name → name, function.parameters → input_schema, function.strict отбрасывается.

Маппинг tool_choice: "auto" → auto | "none" → none | "required" → any | конкретный инструмент → {"type": "tool", "name": "X"}.

Преобразование ответа

Маппинг полей

• stop_reason → finish_reason: end_turn / stop_sequence → stop, max_tokens → length, tool_use → tool_calls.
• input_tokens + cache_read_input_tokens + cache_creation_input_tokens → prompt_tokens (все cache-счётчики суммируются в общий).
• Разбивка по cache-токенам экспонируется в prompt_tokens_details:
  • cache_read_input_tokens → prompt_tokens_details.cached_read_tokens;
  • cache_creation_input_tokens → prompt_tokens_details.cached_write_tokens.
• output_tokens → completion_tokens.
• Блоки thinking → reasoning_details с полями index, type, text, signature.
• Аргументы tool-вызовов конвертируются из JSON-объекта в JSON-строку.

Стриминг

Последовательность событий: message_start → content_block_start → content_block_delta → content_block_stop → message_delta → message_stop.

Типы delta-событий: text_delta → контент | input_json_delta → аргументы инструментов | thinking_delta → reasoning-текст | signature_delta → reasoning-подпись.

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

2. Responses API

Responses API использует тот же эндпоинт /v1/messages, но конвертирует между форматом OpenAI Responses и форматом Anthropic Messages.

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

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

Дополнительные параметры

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-5-sonnet",
    "input": "Hello, how are you?",
    "top_k": 40
  }'

Cache control

Cache-директивы можно добавить к instructions (system) и к input-сообщениям, чтобы включить prompt caching:

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-5-sonnet",
    "instructions": "You are a helpful assistant. This instruction is cached.",
    "instructions_cache_control": {"type": "ephemeral"},
    "input": [
      {
        "type": "text",
        "text": "Answer this question",
        "cache_control": {"type": "ephemeral"}
      }
    ]
  }'

Input и Instructions

• Input — строка оборачивается как user-сообщение, массив конвертируется в сообщения.
• Instructions — становится system-сообщением (та же логика извлечения, что и в Chat Completions).

Поддержка инструментов

Поддерживаемые типы: function, computer_use_preview, web_search, mcp.

Преобразования инструментов те же, что в Chat Completions, плюс: MCP-инструменты мапятся в mcp_servers (server_label → name, server_url → url); computer-инструменты автоматически получают truncation: "auto".

Cache control поддерживается в instructions и input-блоках (примеры — в разделе Cache control выше).

Преобразование ответа

• stop_reason → status: end_turn / stop_sequence → completed, max_tokens → incomplete.
• Верхнеуровневые input_tokens и output_tokens — это совокупные счётчики, включающие cache-составляющие; они мапятся напрямую: input_tokens → input_tokens | output_tokens → output_tokens.
• Cache-счётчики экспонируются отдельно: cache_read_input_tokens → input_tokens_details.cached_read_tokens | cache_creation_input_tokens → input_tokens_details.cached_write_tokens.
• Output-элементы: text → message | tool_use → function_call | thinking → reasoning.

Стриминг

Последовательность событий: message_start → content_block_start → content_block_delta → content_block_stop → message_delta → message_stop.

Особенности обработки: аргументы computer-инструментов аккумулируются по чанкам (выдаются на content_block_stop); для текста и reasoning эмитятся синтетические события content_part.added; MCP-вызовы используют mcp_call_arguments_delta; идентификаторы элементов формируются как msg_{messageID}_item_{outputIndex}.

3. Text Completions (legacy)

Запрос: prompt автоматически оборачивается в \n\nHuman: {prompt}\n\nAssistant: | max_tokens → max_tokens_to_sample | temperature, top_p пробрасываются напрямую | top_k, stop через extra_params (stop → stop_sequences).

Ответ: completion → choices[0].text | stop_reason → finish_reason.

4. Batch API

Форматы запроса: массив requests (CustomID + Params) или input_file_id.

Пагинация: курсорная — after_id, before_id, limit.

Эндпоинты:

• POST /v1/messages/batches — создание;
• GET /v1/messages/batches — листинг;
• GET /v1/messages/batches/{batch_id} — получение по идентификатору;
• POST /v1/messages/batches/{batch_id}/cancel — отмена.

Ответ: JSONL-формат с записями {custom_id, result: {type, message}}.

Маппинг статусов: in_progress → InProgress, canceling → Cancelling, ended → Ended.

Замечание: временные метки RFC3339Nano конвертируются в Unix; поддерживается ретрай по нескольким ключам.

5. Files API

Загрузка: multipart/form-data с полями file (обязательное) и filename (опциональное).

Маппинг полей: id | filename | size_bytes → bytes | created_at (Unix) | mime_type → content_type.

Эндпоинты: POST /v1/files, GET /v1/files (курсорная пагинация), GET /v1/files/{file_id}, DELETE /v1/files/{file_id}, GET /v1/files/{file_id}/content.

Замечание: purpose файла всегда равен "batch", статус всегда "processed".

6. List Models

Запрос: GET /v1/models?limit={defaultPageSize} (без тела).

Маппинг полей: id (с префиксом anthropic/) | display_name → name | created_at (Unix-метка).

Пагинация: токенная — NextPageToken, FirstID, LastID.

Поддержка нескольких ключей: результаты агрегируются по всем ключам и при необходимости фильтруются по allowed_models.