Hướng dẫn tích hợp gắn kết kênh

Định danh ổn định giúp hội thoại liên tục, trợ lý lập trình và tác vụ ngữ cảnh dài tái sử dụng kênh và bộ nhớ đệm ngữ cảnh hiệu quả hơn.

AGTCloud dựa vào định danh ổn định trong yêu cầu để ưu tiên dùng lại kênh đã xử lý thành công cho các yêu cầu tiếp theo. Nếu kênh đó không khả dụng, nền tảng tự chọn kênh khả dụng khác. Định danh này được gọi là khóa gắn kết.

Gắn kết kênh giúp ổn định định tuyến; bộ nhớ đệm ngữ cảnh giúp tái sử dụng phép tính. Kênh ổn định không bảo đảm mọi yêu cầu đều trúng bộ nhớ đệm.

Chọn cách tích hợp

Ưu tiên trường định danh sẵn có trong giao thức. Nếu khó sửa thân yêu cầu, SDK hoặc cổng trung gian có thể truyền định danh ổn định qua tiêu đề yêu cầu.

Dùng chung x-conversation-id

x-conversation-id truyền định danh ổn định qua tiêu đề, không cần thêm trường gắn kết vào thân yêu cầu. Cách này dùng được với các giao thức như OpenAI, Anthropic và 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": "Tiếp tục phân tích vấn đề này."
      }
    ]
  }'

Tiêu đề này phục vụ gắn kết kênh trên nền tảng, mặc định không được coi là tham số mô hình. Giữ cùng một giá trị trong hội thoại liên tục, không tạo lại cho từng yêu cầu.

Thay MODEL_ID trong ví dụ bằng ID mô hình bạn sử dụng và xác thực bằng API Key dành cho việc gọi mô hình.

Tích hợp theo họ mô hình

OpenAI

OpenAI Prompt Caching tự động bật và chủ yếu dựa vào tiền tố yêu cầu giống nhau. Responses và Chat Completions có thể dùng prompt_cache_key để định tuyến bộ nhớ đệm. AGTCloud cũng dùng trường này cho gắn kết kênh và chuyển tiếp đến dịch vụ thượng nguồn hỗ trợ nó.

curl 'https://api.agtcloud.ai/v1/responses' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "input": "Tiếp tục xử lý tác vụ hiện tại.",
    "prompt_cache_key": "project_knowledge_v3"
  }'

Khóa gắn kết có thể đại diện cho hội thoại, dự án, phiên bản cơ sở tri thức hoặc kho mã. Để tiếp tục hội thoại Responses hiện có, thêm previous_response_id bằng ID phản hồi trước đó. Yêu cầu đầu tiên không cần trường này.

Claude / Anthropic

Claude dùng cache_control trong khối nội dung để đánh dấu tiền tố tái sử dụng và cũng hỗ trợ lưu đệm tự động nhiều lượt. metadata.user_id có thể làm khóa gắn kết trên nền tảng; ứng dụng như Claude Code thường đã gửi định danh ổn định dạng này. Đây không phải điểm ngắt bộ nhớ đệm và không thay thế 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": "Đặt các quy tắc nghiệp vụ và ràng buộc công cụ ổn định tại đây.",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Tiếp tục phân tích kho mã này."
      }
    ]
  }'

Claude xây tiền tố bộ nhớ đệm theo thứ tự tools, system, messages. Sửa định nghĩa công cụ, system hoặc thông điệp đã lưu đệm sẽ ảnh hưởng cấp tương ứng và các cấp sau. Có thể chọn TTL ngắn hoặc dài hơn theo khả năng của dịch vụ thượng nguồn.

Gemini

Dùng x-conversation-id để giữ gắn kết kênh, rồi chọn cách lưu đệm theo tình huống:

• Bộ nhớ đệm ngầm định: Bật mặc định với Gemini 2.5 trở lên, phù hợp hội thoại thông thường tái sử dụng tiền tố ổn định trong thời gian ngắn.
• Bộ nhớ đệm tường minh: Tạo tài nguyên qua /v1beta/cachedContents, sau đó tham chiếu bằng cachedContent. Phù hợp tài liệu dài, video dài, cơ sở tri thức cố định và phân tích kho mã. Ứng dụng cần quản lý việc tạo, thời hạn và các lần tham chiếu tiếp theo.

DeepSeek

DeepSeek tự bật lưu đệm ngữ cảnh trên đĩa và tái sử dụng tiền tố đầy đủ, ổn định. deepseek-v4-flash và deepseek-v4-pro dùng user_id để phân biệt người dùng cho xử lý an toàn, giới hạn tốc độ theo người dùng và cách ly K/V Cache.

Yêu cầu có cùng mô hình và user_id sẽ ưu tiên tái sử dụng kênh đã thành công trước đó.

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": "Đặt quy tắc nghiệp vụ, mô tả công cụ hoặc tóm tắt cơ sở tri thức ổn định tại đây."
      },
      {
        "role": "user",
        "content": "Tiếp tục phân tích vấn đề này."
      }
    ]
  }'

user_id chỉ dùng ký tự ASCII, dài tối đa 512 ký tự và nên cố định lâu dài cho cùng người dùng. Nếu không có ID người dùng, có thể dùng định danh cố định do ứng dụng tạo. Nếu không sửa được thân yêu cầu, dùng cách x-conversation-id ở trên.

Giới hạn đồng thời mặc định cho mỗi user_id:

Khi không truyền user_id, nền tảng tự cấp định danh khả dụng từ nhóm UID đã cấu hình. Yêu cầu vẫn gửi bình thường.

Xem usage.prompt_cache_hit_tokens và usage.prompt_cache_miss_tokens trong phản hồi để biết số token trúng và không trúng bộ nhớ đệm.

Qwen

Qwen / DashScope hỗ trợ bộ nhớ đệm ngầm định, tường minh và Session Cache. Với qwen3.6-plus, qwen3.6-flash, qwen3-coder-plus và các mô hình tương tự, chọn theo giao thức gọi:

• Chat Completions: Lưu đệm ngầm định tự bật. Để đánh dấu nội dung tái sử dụng, thêm cache_control vào khối nội dung.
• Responses nhiều lượt: Dùng previous_response_id để tiếp tục phản hồi và thêm tiêu đề x-dashscope-session-cache: enable để bật Session Cache.

Cả hai cách đều có thể truyền thêm x-conversation-id để giữ gắn kết kênh. Ví dụ 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": "Đặt ngữ cảnh dài ổn định vượt ngưỡng bộ nhớ đệm tại đây.",
            "cache_control": { "type": "ephemeral" }
          }
        ]
      },
      {
        "role": "user",
        "content": "Trả lời câu hỏi dựa trên nội dung ở trên."
      }
    ],
    "stream": false
  }'

GLM / Z.AI

GLM-5, GLM-5.1, GLM-4.7, GLM-4.6 và GLM-4.5 cung cấp lưu đệm ngữ cảnh tự động, phù hợp tác vụ dài, lập trình và Agent. Dùng x-conversation-id ổn định cho cùng dự án hoặc tác vụ Agent:

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": "Đặt mục tiêu Agent, ràng buộc công cụ và bối cảnh dự án ổn định tại đây."
      },
      {
        "role": "user",
        "content": "Tiếp tục bước tiếp theo."
      }
    ],
    "stream": false
  }'

Xem usage.prompt_tokens_details.cached_tokens trong phản hồi để biết số token được lưu đệm. Khi giữ lại nội dung suy nghĩ, cũng giữ nguyên thứ tự và nội dung các đoạn lịch sử cần tái sử dụng.

Khuyến nghị sử dụng

• Giữ tiền tố ổn định: Đặt chỉ dẫn cố định, định nghĩa công cụ, tài liệu dài và tóm tắt lịch sử ở đầu; câu hỏi hiện tại, thời gian và nhật ký tạm ở cuối. Tránh sắp lại công cụ, viết lại lịch sử không đổi hoặc chèn giá trị ngẫu nhiên.
• Chọn định danh đúng phạm vi: ID hội thoại cố định trong cùng hội thoại; ID người dùng cố định lâu dài cho cùng người dùng; định danh dự án hoặc cơ sở tri thức phân biệt theo dự án và phiên bản. Không dùng lẫn giữa các bên thuê, cũng không thay định danh cần phân biệt người dùng bằng định danh dự án dùng chung.
• Tránh dữ liệu nhạy cảm dạng rõ: Không dùng số điện thoại, email, số giấy tờ định danh hoặc API Key làm khóa gắn kết. Có thể biến đổi không đảo ngược định danh nghiệp vụ. Không dùng Request ID chỉ có hiệu lực cho một yêu cầu.
• Chú ý thời hạn: Nền tảng cấu hình thời hạn ánh xạ gắn kết; nên đặt gần cửa sổ bộ nhớ đệm thượng nguồn, thường tham khảo 5 phút đến 1 giờ. Không cần thêm TTL vào yêu cầu. Giữ định danh không đổi không kéo dài thời hạn bộ nhớ đệm thượng nguồn.

Khắc phục vấn đề thường gặp

Một lần không trúng bộ nhớ đệm không đủ chứng minh gắn kết kênh đã thất bại. Nếu yêu cầu lỗi, xem Lỗi và khắc phục sự cố.

Tài liệu tham khảo

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