Cohere

Обзор

Cohere использует структуру API, отличную от формата OpenAI. Meridian выполняет следующие преобразования:

• Переименование параметров — например, max_completion_tokens → max_tokens, top_p → p, stop → stop_sequences.
• Преобразование контента сообщений — поддерживаются строки и массивы блоков контента.
• Преобразование инструментов — определения tools и tool_choice приводятся к формату Cohere.
• Преобразование thinking/reasoning — параметры reasoning мапятся в структуру thinking Cohere.
• Преобразование response format — обработка JSON-схемы адаптирована под формат Cohere.

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

1. Chat Completions

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

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

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

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

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

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

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/command-r-plus",
    "messages": [{"role": "user", "content": "Hello"}],
    "top_k": 40,
    "safety_mode": "STRICT",
    "log_probs": true,
    "strict_tool_choice": false
  }'

Reasoning / Thinking

Документация: см. Reasoning.

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

• reasoning.effort → thinking.type (мапится в "enabled" или "disabled").
• reasoning.max_tokens → thinking.token_budget (бюджет токенов на thinking).

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

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

Пример

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

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

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

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

• Строковый контент: сообщения могут иметь простой строковый контент.
• Блоки контента: сообщения могут иметь массивы блоков контента (text, images, thinking).
• Преобразование изображений: поддерживаются блоки image_url с URL.
• Tool calls: конвертируются из tool calls assistant-сообщений в формат Cohere.
• Tool messages: результаты tool call передаются с tool_call_id.

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

Определения инструментов адаптируются под формат Cohere со следующими маппингами:

• Функция name → name (без изменений).
• Функция parameters → parameters (гибкий JSON-формат).
• Strict-режим (strict: true) тихо отбрасывается (не поддерживается).

Маппинг tool_choice:

• "none" → "NONE";
• "auto" или "required" → "REQUIRED" или "AUTO";
• Выбор конкретного инструмента → "REQUIRED" (Cohere использует выбор на уровне функции).

Response Format

Поддерживаемые форматы:

• text — обычный текстовый ответ;
• json_object — структурированный JSON-ответ;
• json_schema — JSON с валидацией по схеме (конвертируется в json_object).

Схема передаётся через поле response_format.json_schema.

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

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

• finish_reason: COMPLETE / STOP_SEQUENCE → stop, MAX_TOKENS → length, TOOL_CALL → tool_calls.
• input_tokens → prompt_tokens | output_tokens → completion_tokens.
• cached_tokens → prompt_tokens_details.cached_tokens (если присутствует).
• Аргументы tool call конвертируются из строки в строку (преобразование не требуется, Cohere использует строковый формат).

Стриминг

Последовательность событий: message-start → content-start → content-delta → content-end → message-end.

Типы delta-событий:

• content-delta с текстом → контент сообщения;
• content-delta с thinking → reasoning-текст;
• tool-call-start/delta/end → события tool call;
• tool-plan-delta → вывод планирования tool.

Нюансы

2. Responses API

Responses API использует тот же эндпоинт /v2/chat, но конвертирует между форматом OpenAI Responses и форматом Cohere.

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

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

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

Используйте extra_params (SDK) или передавайте напрямую в теле запроса (Gateway):

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/command-r-plus",
    "input": "Hello, how are you?",
    "top_k": 40,
    "stop": [".", "!"]
  }'

Input и Instructions

• Input: строка преобразуется в user-сообщение, массив конвертируется в сообщения.
• Instructions: становится system-сообщением (добавляется в начало массива сообщений).

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

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

Преобразования инструментов те же, что в Chat Completions.

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

• text → message | tool_use → function_call.
• input_tokens / output_tokens сохраняются.
• Детали токенов с поддержкой cached tokens.

Стриминг

Последовательность событий: message-start → content-start → content-delta → content-end → message-end.

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

• Аргументы tool call аккумулируются по чанкам;
• Синтетические события output_item.added эмитятся для text/reasoning;
• Стабильные ID элементов формируются как msg_{messageID}_item_{outputIndex}.

3. Embeddings

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

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

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

Используйте extra_params для опций embedding, специфичных для Cohere:

curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/embed-english-v3.0",
    "input": ["text to embed"],
    "input_type": "search_query",
    "embedding_types": ["float"],
    "truncate": "START"
  }'

Критичные замечания

• Input Type обязателен: модели Cohere v3+ требуют параметр input_type (по умолчанию "search_document").
• Embedding Types: укажите, какие типы embedding возвращать (например, "float", "int8").

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

• embeddings.float → data[].embedding.
• meta.tokens → информация об usage.
• Обрабатываются несколько типов embedding.

4. List Models

Запрос: GET /v1/models?page_size={defaultPageSize}.

Маппинг полей: данные модели конвертируются в стандартный формат.

Пагинация: курсорная — через next_page_token.

Замечание: фильтры endpoint и default_only доступны через extra_params.