채널 어피니티 연동 가이드

연속 대화, 코딩 도우미, 긴 컨텍스트 작업에서는 안정적인 식별자를 통해 채널과 컨텍스트 캐시의 재사용 가능성을 높일 수 있습니다.

AGTCloud는 요청의 안정적인 식별자를 바탕으로 이후 요청이 이전에 성공한 채널을 우선 재사용하도록 합니다. 해당 채널을 사용할 수 없으면 다른 사용 가능한 채널을 자동으로 선택합니다. 이 식별자를 어피니티 키라고 합니다.

채널 어피니티는 라우팅을 안정화하고, 컨텍스트 캐시는 계산을 재사용합니다. 채널이 안정적이어도 매번 캐시가 적중하는 것은 아닙니다.

연동 방식 선택

프로토콜에 이미 있는 식별자 필드를 우선 활용하세요. 요청 본문을 수정하기 어렵다면 SDK나 게이트웨이에서 헤더로 안정적인 식별자를 전달할 수 있습니다.

공통 헤더 x-conversation-id 사용

x-conversation-id는 요청 헤더로 안정적인 식별자를 전달하므로 본문에 어피니티 식별자 필드를 추가하지 않아도 됩니다. OpenAI, Anthropic, Gemini 등의 프로토콜에서 사용할 수 있습니다:

curl 'https://api.agtcloud.ai/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.ai/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 대화를 이어갈 때는 이전 응답 ID를 previous_response_id에 추가하세요. 첫 요청에는 필요하지 않습니다.

Claude / Anthropic

Claude는 콘텐츠 블록의 cache_control로 재사용할 접두사를 표시하며 자동 다중 턴 캐시도 지원합니다. metadata.user_id는 플랫폼 어피니티 키로 사용할 수 있고, Claude Code 같은 클라이언트는 보통 이런 안정적인 식별자를 이미 전송합니다. 이 값은 캐시 중단점이 아니며 cache_control을 대체하지 않습니다.

curl 'https://api.agtcloud.ai/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.ai/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로 응답을 이어가고 x-dashscope-session-cache: enable 헤더를 추가해 Session Cache를 활성화하세요.

두 방식 모두 x-conversation-id를 함께 전달해 채널 어피니티를 유지할 수 있습니다. 다음은 Chat Completions 예제입니다:

curl 'https://api.agtcloud.ai/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 등은 자동 컨텍스트 캐시를 제공하며 장기 작업, 코드, Agent에 적합합니다. 같은 프로젝트나 Agent 작업에서는 안정적인 x-conversation-id를 사용하세요:

curl 'https://api.agtcloud.ai/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": "안정적인 Agent 작업 목표, 도구 제약 및 프로젝트 배경을 여기에 배치합니다."
      },
      {
        "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