Cài đặt công cụ agentic

Công cụ agentic gửi nội dung file, output lệnh và toàn bộ lịch sử hội thoại ở mỗi bước. Prompt lớn như vậy có thể mất hàng chục giây trước khi token đầu tiên xuất hiện. Nếu ứng dụng của bạn bỏ cuộc trước, request vẫn bị tính nhưng bạn không nhận được gì. Hãy đặt timeout, streaming, retry và kích thước context như bên dưới.

Vì sao điều này quan trọng

• Request bị ngắt trước khi có phản hồi vẫn bị tính. Ngay khi request đến, máy chủ AI bắt đầu xử lý toàn bộ prompt. Nếu ứng dụng của bạn ngắt trước (timeout, nút dừng, mất kết nối), chi phí xử lý đã phát sinh nhưng bạn không nhận được phản hồi.
• Prompt khổng lồ cần hơn 30 giây trước token đầu tiên. Prompt agentic hàng trăm KB với hàng nghìn tin nhắn có thể vượt giới hạn mặc định của nhiều ứng dụng (30 hoặc 60 giây) trước khi một token nào được trả ra.
• Streaming giữ kết nối luôn sống. Khi bật streaming, máy chủ của chúng tôi gửi header ngay lập tức, rồi gửi tín hiệu keepalive mỗi 10 giây trong lúc chờ phản hồi. Thứ vẫn có thể cắt kết nối là giới hạn thời gian tổng của ứng dụng, nên hãy đặt tối thiểu 300 giây.
• Chọn model nhanh cho context lớn. Với phiên dài hoặc repo lớn, hãy dùng model nhanh hơn và để dành model lớn cho các bước thật sự cần. So sánh tại trang Bảng giá.

Hướng dẫn chung cho mọi công cụ

Timeout

Tối thiểu 300 giây. Chú ý đơn vị: có công cụ dùng giây (300), có công cụ dùng mili giây (300000).

Streaming

Hãy bật lên. Không có streaming thì không có dữ liệu nào chạy cho đến khi phản hồi hoàn tất, nên proxy và ứng dụng bỏ cuộc sớm hơn.

Retry

Giữ ở mức thấp (0–3). Retry sau timeout là một request mới và cũng bị tính phí. Hãy sửa timeout trước thay vì tăng số lần retry.

Context

Giữ context nhỏ. Dùng compact/tóm tắt tự động, mở phiên mới cho mỗi tác vụ và loại trừ thư mục lớn (node_modules, build, data).

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.geraikita.com",
    "ANTHROPIC_AUTH_TOKEN": "gk-xxxxxxxx",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_MAX_RETRIES": "3",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "60"
  }
}

{
  "provider": {
    "geraikita": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Geraikita AI",
      "options": {
        "baseURL": "https://ai.geraikita.com/v1",
        "apiKey": "gk-xxxxxxxx",
        "timeout": 600000
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": { "context": 128000, "output": 16000 }
        }
      }
    }
  },
  "compaction": { "auto": true }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "geraikita": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://ai.geraikita.com/v1",
        "apiKey": "{env:GERAIKITA_API_KEY}",
        "headerTimeout": 300000,
        "chunkTimeout": 300000
      }
    }
  },
  "compaction": { "auto": true }
}

models:
  - name: Claude Sonnet 5 (Geraikita)
    provider: openai
    model: claude-sonnet-5
    apiBase: https://ai.geraikita.com/v1
    apiKey: gk-xxxxxxxx
    requestOptions:
      timeout: 600        # giây, không phải mili giây
    defaultCompletionOptions:
      contextLength: 64000  # nhỏ hơn = lịch sử bị cắt bớt
      maxTokens: 8192

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.geraikita.com/v1",
    api_key="gk-xxxxxxxx",
    timeout=600.0,   # giây
    max_retries=1,   # retry sau timeout cũng bị tính phí
)
stream = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Halo!"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import anthropic

client = anthropic.Anthropic(
    base_url="https://ai.geraikita.com",   # không có /v1
    api_key="gk-xxxxxxxx",
    timeout=600.0,   # giây
    max_retries=1,   # retry sau timeout cũng bị tính phí
)
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Halo!"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

curl https://ai.geraikita.com/v1/chat/completions \
  --max-time 600 -N \
  -H "Authorization: Bearer gk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","stream":true,"messages":[{"role":"user","content":"Halo!"}]}'

Điều khoản tính phí

Câu hỏi thường gặp