Руководство по подключению с привязкой к каналу

Стабильные идентификаторы помогают повторно использовать каналы и кеш контекста в длительных диалогах, помощниках по программированию и задачах с большим контекстом.

AGTCloud использует стабильный идентификатор запроса, чтобы последующие запросы преимущественно направлялись в ранее успешно использованный канал. Если он недоступен, платформа автоматически выбирает другой доступный канал. Этот идентификатор называется ключом привязки.

Привязка к каналу стабилизирует маршрутизацию, а кеш контекста позволяет повторно использовать вычисления. Стабильный канал не гарантирует попадание в кеш при каждом запросе.

Выбор способа подключения

Предпочитайте поля идентификации, уже предусмотренные протоколом. Если менять тело запроса неудобно, SDK или шлюз может передавать стабильный идентификатор в заголовке.

Общий заголовок x-conversation-id

x-conversation-id передает стабильный идентификатор в заголовке, поэтому добавлять поле привязки в тело запроса не требуется. Способ подходит для протоколов OpenAI, Anthropic, Gemini и других:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: conversation_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Продолжите анализ этой проблемы."
      }
    ]
  }'

Этот заголовок используется для привязки к каналу на платформе и по умолчанию не является параметром модели. Сохраняйте одно значение в рамках непрерывного диалога, а не создавайте новое для каждого запроса.

Замените MODEL_ID в примерах на ID используемой модели. Для аутентификации нужен API Key для вызовов моделей.

Подключение по семействам моделей

OpenAI

OpenAI Prompt Caching включается автоматически и в основном зависит от совпадения префиксов запросов. Responses и Chat Completions могут использовать prompt_cache_key для маршрутизации кеша. AGTCloud также использует его для привязки к каналу и передает провайдерам, поддерживающим это поле.

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "input": "Продолжите текущую задачу.",
    "prompt_cache_key": "project_knowledge_v3"
  }'

Ключ привязки может обозначать диалог, проект, версию базы знаний или репозиторий. Для продолжения существующего диалога Responses дополнительно укажите previous_response_id с ID предыдущего ответа. Для первого запроса поле не требуется.

Claude / Anthropic

Claude отмечает повторно используемые префиксы с помощью cache_control в блоках содержимого и поддерживает автоматическое кеширование диалога. metadata.user_id может служить ключом привязки на платформе; клиенты, такие как Claude Code, часто уже передают подобный стабильный идентификатор. Это не точка кеширования и не замена cache_control.

curl 'https://api.agtcloud.cn/v1/messages' \
  -H 'x-api-key: your-api-key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "metadata": {
      "user_id": "conversation_3cb9dd9a4819594254a779c90a2171"
    },
    "system": [
      {
        "type": "text",
        "text": "Здесь разместите стабильные бизнес-правила и ограничения инструментов.",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Продолжите анализ этого репозитория."
      }
    ]
  }'

Claude строит префиксы кеша по уровням tools, system, messages. Изменение определений инструментов, system или кешированных сообщений влияет на соответствующий и последующие уровни. Доступны короткие или более длительные TTL в зависимости от возможностей провайдера.

Gemini

Используйте x-conversation-id для привязки к каналу и выберите кеширование под свою задачу:

• Неявный кеш: Включен по умолчанию для Gemini 2.5 и более новых моделей. Подходит для обычных диалогов с повторным использованием стабильного префикса за короткий период.
• Явный кеш: Создайте ресурс через /v1beta/cachedContents, затем ссылайтесь на него через cachedContent. Подходит для длинных документов и видео, фиксированных баз знаний и анализа репозиториев. Клиент управляет созданием, сроком действия и последующими ссылками на ресурс.

DeepSeek

DeepSeek автоматически включает дисковый кеш контекста и повторно использует полные стабильные префиксы. deepseek-v4-flash и deepseek-v4-pro используют user_id для различения пользователей при проверках безопасности, ограничении запросов по пользователю и изоляции K/V Cache.

Запросы с одинаковой моделью и user_id преимущественно используют ранее успешно выбранный канал.

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "user_id": "user_123",
    "messages": [
      {
        "role": "system",
        "content": "Здесь разместите стабильные бизнес-правила, описания инструментов или сводку базы знаний."
      },
      {
        "role": "user",
        "content": "Продолжите анализ этой проблемы."
      }
    ]
  }'

user_id должен содержать только ASCII, не более 512 символов, и оставаться постоянным для одного пользователя. Если ID пользователя недоступен, подойдет стабильный идентификатор, созданный приложением. Если тело изменить нельзя, используйте описанный выше x-conversation-id.

Ограничения параллельных запросов по умолчанию для каждого user_id:

Если user_id не передан, платформа автоматически назначает доступный идентификатор из настроенного пула UID. Запрос по-прежнему можно отправить обычным образом.

Поля ответа usage.prompt_cache_hit_tokens и usage.prompt_cache_miss_tokens показывают число токенов с попаданием и без попадания в кеш.

Qwen

Qwen / DashScope поддерживает неявный кеш, явный кеш и Session Cache. Для qwen3.6-plus, qwen3.6-flash, qwen3-coder-plus и подобных моделей выбирайте способ по протоколу вызова:

• Chat Completions: Неявный кеш включается автоматически. Для пометки повторно используемого содержимого добавьте cache_control в блоки содержимого.
• Многошаговый диалог Responses: Продолжайте ответ через previous_response_id и включайте Session Cache заголовком x-dashscope-session-cache: enable.

В обоих случаях можно дополнительно передавать x-conversation-id для привязки к каналу. Пример Chat Completions:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: conversation_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Здесь разместите стабильный длинный контекст, превышающий порог кеширования.",
            "cache_control": { "type": "ephemeral" }
          }
        ]
      },
      {
        "role": "user",
        "content": "Ответьте на вопрос на основе приведенного выше содержимого."
      }
    ],
    "stream": false
  }'

GLM / Z.AI

GLM-5, GLM-5.1, GLM-4.7, GLM-4.6 и GLM-4.5 предоставляют автоматический кеш контекста для длительных задач, программирования и агентов. Для одного проекта или задачи агента используйте стабильный x-conversation-id:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: agent_task_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": "Здесь разместите стабильные цели агента, ограничения инструментов и контекст проекта."
      },
      {
        "role": "user",
        "content": "Продолжите следующий шаг."
      }
    ],
    "stream": false
  }'

Число кешированных токенов доступно в usage.prompt_tokens_details.cached_tokens. При сохранении рассуждений также сохраняйте порядок и содержимое исторических фрагментов, которые нужно использовать повторно.

Рекомендации

• Сохраняйте префиксы: Размещайте постоянные инструкции, определения инструментов, длинные документы и сводки истории в начале, а текущий вопрос, время и временные логи в конце. Не переставляйте инструменты, не переписывайте неизменную историю и не вставляйте случайные значения.
• Выбирайте область действия идентификатора: ID диалога фиксируется в рамках диалога, ID пользователя остается постоянным для этого пользователя, а проекты и версии баз знаний получают свои идентификаторы. Не смешивайте их между арендаторами и не используйте общий идентификатор проекта вместо идентификатора, который должен различать пользователей.
• Не передавайте чувствительные данные открытым текстом: Не используйте телефон, электронную почту, номера документов или API Key как ключ привязки. Бизнес-идентификаторы можно необратимо преобразовать. Не используйте одноразовый Request ID.
• Учитывайте срок действия: Время жизни привязки задается платформой; рекомендуется согласовать его с окном кеша провайдера, обычно от 5 минут до 1 часа. Не добавляйте отдельный TTL в запрос. Неизменный идентификатор не продлевает срок кеша провайдера.

Устранение типичных проблем

Промах кеша сам по себе не доказывает сбой привязки к каналу. При ошибке запроса см. Ошибки и диагностика.

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

• OpenAI Prompt Caching
• Claude Prompt Caching
• Gemini Context Caching
• DeepSeek Context Caching
• Qwen Context Cache
• GLM / Z.AI Context Caching