picoclaw/docs/vi/providers.md

🔌 Nhà Cung Cấp và Cấu Hình Mô Hình

Quay lại README

Nhà Cung Cấp

Note

Groq cung cấp chuyển đổi giọng nói miễn phí qua Whisper. Nếu được cấu hình, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển đổi ở cấp agent.

Provider	Purpose	Get API Key
gemini	LLM (Gemini direct)	aistudio.google.com
zhipu	LLM (Zhipu direct)	bigmodel.cn
volcengine	LLM(Volcengine direct)	volcengine.com
openrouter	LLM (recommended, access to all models)	openrouter.ai
anthropic	LLM (Claude direct)	console.anthropic.com
openai	LLM (GPT direct)	platform.openai.com
deepseek	LLM (DeepSeek direct)	platform.deepseek.com
qwen	LLM (Qwen direct)	dashscope.console.aliyun.com
groq	LLM + Voice transcription (Whisper)	console.groq.com
cerebras	LLM (Cerebras direct)	cerebras.ai
vivgrid	LLM (Vivgrid direct)	vivgrid.com
moonshot	LLM (Kimi/Moonshot direct)	platform.moonshot.cn
minimax	LLM (Minimax direct)	platform.minimaxi.com
avian	LLM (Avian direct)	avian.io
mistral	LLM (Mistral direct)	console.mistral.ai
longcat	LLM (Longcat direct)	longcat.ai
modelscope	LLM (ModelScope direct)	modelscope.cn

Cấu Hình Mô Hình (model_list)

Có gì mới? PicoClaw hiện sử dụng cách tiếp cận cấu hình tập trung vào mô hình. Chỉ cần chỉ định định dạng vendor/model (ví dụ: zhipu/glm-4.7) để thêm provider mới — không cần thay đổi code!

Thiết kế này cũng cho phép hỗ trợ đa agent với lựa chọn provider linh hoạt:

• Agent khác nhau, provider khác nhau: Mỗi agent có thể sử dụng provider LLM riêng
• Fallback mô hình: Cấu hình mô hình chính và dự phòng cho khả năng phục hồi
• Cân bằng tải: Phân phối yêu cầu qua nhiều endpoint
• Cấu hình tập trung: Quản lý tất cả provider tại một nơi

📋 Tất Cả Vendor Được Hỗ Trợ

Vendor	model Prefix	Default API Base	Protocol	API Key
OpenAI	openai/	https://api.openai.com/v1	OpenAI	Get Key
Anthropic	anthropic/	https://api.anthropic.com/v1	Anthropic	Get Key
智谱 AI (GLM)	zhipu/	https://open.bigmodel.cn/api/paas/v4	OpenAI	Get Key
DeepSeek	deepseek/	https://api.deepseek.com/v1	OpenAI	Get Key
Google Gemini	gemini/	https://generativelanguage.googleapis.com/v1beta	OpenAI	Get Key
Groq	groq/	https://api.groq.com/openai/v1	OpenAI	Get Key
Moonshot	moonshot/	https://api.moonshot.cn/v1	OpenAI	Get Key
通义千问 (Qwen)	qwen/	https://dashscope.aliyuncs.com/compatible-mode/v1	OpenAI	Get Key
NVIDIA	nvidia/	https://integrate.api.nvidia.com/v1	OpenAI	Get Key
Ollama	ollama/	http://localhost:11434/v1	OpenAI	Local (no key needed)
OpenRouter	openrouter/	https://openrouter.ai/api/v1	OpenAI	Get Key
LiteLLM Proxy	litellm/	http://localhost:4000/v1	OpenAI	Your LiteLLM proxy key
VLLM	vllm/	http://localhost:8000/v1	OpenAI	Local
Cerebras	cerebras/	https://api.cerebras.ai/v1	OpenAI	Get Key
VolcEngine (Doubao)	volcengine/	https://ark.cn-beijing.volces.com/api/v3	OpenAI	Get Key
神算云	shengsuanyun/	https://router.shengsuanyun.com/api/v1	OpenAI	-
BytePlus	byteplus/	https://ark.ap-southeast.bytepluses.com/api/v3	OpenAI	Get Key
Vivgrid	vivgrid/	https://api.vivgrid.com/v1	OpenAI	Get Key
LongCat	longcat/	https://api.longcat.chat/openai	OpenAI	Get Key
ModelScope (魔搭)	modelscope/	https://api-inference.modelscope.cn/v1	OpenAI	Get Token
Antigravity	antigravity/	Google Cloud	Custom	OAuth only
GitHub Copilot	github-copilot/	localhost:4321	gRPC	-

Cấu Hình Cơ Bản

{
  "model_list": [
    {
      "model_name": "ark-code-latest",
      "model": "volcengine/ark-code-latest",
      "api_keys": ["sk-your-api-key"]
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_keys": ["sk-your-openai-key"]
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_keys": ["sk-ant-your-key"]
    },
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_keys": ["your-zhipu-key"]
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "gpt-5.4"
    }
  }
}

Các trường entry model_list

Trường	Kiểu	Bắt buộc	Mô tả
model_name	string	Có	Tên duy nhất để tham chiếu model này trong cấu hình agent
model	string	Có	Định danh nhà cung cấp/model (ví dụ: openai/gpt-5.4, azure/gpt-5.4, anthropic/claude-sonnet-4.6)
api_keys	string[]	Có*	Khóa API xác thực. Nhiều khóa cho phép xoay vòng theo yêu cầu. Không cần thiết cho provider nội bộ (Ollama, LM Studio, VLLM)
api_base	string	Không	Ghi đè URL endpoint API mặc định
proxy	string	Không	URL proxy HTTP cho entry model này
user_agent	string	Không	Header User-Agent tùy chỉnh gửi với yêu cầu API (được hỗ trợ bởi provider OpenAI-compatible, Anthropic và Azure)
request_timeout	int	Không	Timeout yêu cầu tính bằng giây (mặc định khác nhau tùy provider)
max_tokens_field	string	Không	Ghi đè tên trường max tokens trong request body (ví dụ: max_completion_tokens cho model o1)
thinking_level	string	Không	Mức độ tư duy mở rộng: off, low, medium, high, xhigh hoặc adaptive
extra_body	object	Không	Các trường bổ sung để chèn vào mỗi request body
rpm	int	Không	Giới hạn tốc độ yêu cầu mỗi phút
fallbacks	string[]	Không	Tên model dự phòng cho failover tự động
enabled	bool	Không	Kích hoạt hay vô hiệu hóa entry model này (mặc định: true)

Ví Dụ Theo Vendor

OpenAI

{
  "model_name": "gpt-5.4",
  "model": "openai/gpt-5.4",
  "api_keys": ["sk-..."]
}

VolcEngine (Doubao)

{
  "model_name": "ark-code-latest",
  "model": "volcengine/ark-code-latest",
  "api_keys": ["sk-..."]
}

智谱 AI (GLM)

{
  "model_name": "glm-4.7",
  "model": "zhipu/glm-4.7",
  "api_keys": ["your-key"]
}

DeepSeek

{
  "model_name": "deepseek-chat",
  "model": "deepseek/deepseek-chat",
  "api_keys": ["sk-..."]
}

Anthropic (với API key)

{
  "model_name": "claude-sonnet-4.6",
  "model": "anthropic/claude-sonnet-4.6",
  "api_keys": ["sk-ant-your-key"]
}

Chạy picoclaw auth login --provider anthropic để dán API token.

Anthropic Messages API (định dạng native)

Để truy cập trực tiếp API Anthropic hoặc endpoint tùy chỉnh chỉ hỗ trợ định dạng message native của Anthropic:

{
  "model_name": "claude-opus-4-6",
  "model": "anthropic-messages/claude-opus-4-6",
  "api_keys": ["sk-ant-your-key"],
  "api_base": "https://api.anthropic.com"
}

Sử dụng giao thức anthropic-messages khi:

• Sử dụng proxy bên thứ ba chỉ hỗ trợ endpoint native /v1/messages của Anthropic (không tương thích OpenAI /v1/chat/completions)
• Kết nối đến dịch vụ như MiniMax, Synthetic yêu cầu định dạng message native của Anthropic
• Giao thức anthropic hiện tại trả về lỗi 404 (cho thấy endpoint không hỗ trợ định dạng tương thích OpenAI)

Lưu ý: Giao thức anthropic sử dụng định dạng tương thích OpenAI (/v1/chat/completions), trong khi anthropic-messages sử dụng định dạng native của Anthropic (/v1/messages). Chọn dựa trên định dạng endpoint hỗ trợ.

Ollama (local)

{
  "model_name": "llama3",
  "model": "ollama/llama3"
}

Proxy/API Tùy Chỉnh

{
  "model_name": "my-custom-model",
  "model": "openai/custom-model",
  "api_base": "https://my-proxy.com/v1",
  "api_keys": ["sk-..."],
  "user_agent": "MyApp/1.0",
  "request_timeout": 300
}

LiteLLM Proxy

{
  "model_name": "lite-gpt4",
  "model": "litellm/lite-gpt4",
  "api_base": "http://localhost:4000/v1",
  "api_keys": ["sk-..."]
}

PicoClaw chỉ loại bỏ tiền tố ngoài litellm/ trước khi gửi yêu cầu, nên alias proxy như litellm/lite-gpt4 gửi lite-gpt4, trong khi litellm/openai/gpt-4o gửi openai/gpt-4o.

Cân Bằng Tải

Cấu hình nhiều endpoint cho cùng tên mô hình — PicoClaw sẽ tự động round-robin giữa chúng:

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api1.example.com/v1",
      "api_keys": ["sk-key1"]
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api2.example.com/v1",
      "api_keys": ["sk-key2"]
    }
  ]
}

Di Chuyển Từ Cấu Hình Legacy providers

Cấu hình providers cũ đã bị deprecated và đã được loại bỏ trong V2. Các cấu hình V0/V1 hiện có sẽ được tự động migrate.

Cấu hình cũ (ngừng hỗ trợ):

{
  "providers": {
    "zhipu": {
      "api_key": "your-key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  },
  "agents": {
    "defaults": {
      "provider": "zhipu",
      "model": "glm-4.7"
    }
  }
}

Cấu hình mới (khuyến nghị):

{
  "version": 2,
  "model_list": [
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_keys": ["your-key"]
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "glm-4.7"
    }
  }
}

Để xem hướng dẫn di chuyển chi tiết, xem migration/model-list-migration.md.

Kiến Trúc Provider

PicoClaw định tuyến provider theo họ giao thức:

• Giao thức tương thích OpenAI: OpenRouter, gateway tương thích OpenAI, Groq, Zhipu, và endpoint kiểu vLLM.
• Giao thức Anthropic: Hành vi API native của Claude.
• Đường dẫn Codex/OAuth: Tuyến xác thực OAuth/token của OpenAI.

Điều này giữ runtime nhẹ trong khi làm cho backend tương thích OpenAI mới chủ yếu là thao tác cấu hình (api_base + api_keys).

Zhipu

1. Lấy API key và URL base

• Lấy API key

2. Cấu hình

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "glm-4.7",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "zhipu": {
      "api_key": "Your API Key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  }
}

3. Chạy

picoclaw agent -m "Hello"

Ví dụ cấu hình đầy đủ

{
  "agents": {
    "defaults": {
      "model_name": "anthropic/claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer"
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx"
    },
    "groq": {
      "api_key": "gsk_xxx"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC...",
      "allow_from": ["123456789"]
    },
    "discord": {
      "enabled": true,
      "token": "",
      "allow_from": [""]
    },
    "whatsapp": {
      "enabled": false,
      "bridge_url": "ws://localhost:3001",
      "use_native": false,
      "session_store_path": "",
      "allow_from": []
    },
    "feishu": {
      "enabled": false,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "app_id": "",
      "app_secret": "",
      "allow_from": []
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "BSA...",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://localhost:8888",
        "max_results": 5
      }
    },
    "cron": {
      "exec_timeout_minutes": 5
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

---

📝 So Sánh API Key

Service	Pricing	Use Case
OpenRouter	Free: 200K tokens/month	Multiple models (Claude, GPT-4, etc.)
Volcengine CodingPlan	¥9.9/first month	Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.)
Zhipu	Free: 200K tokens/month	Suitable for Chinese users
Brave Search	$5/1000 queries	Web search functionality
SearXNG	Free (self-hosted)	Privacy-focused metasearch (70+ engines)
Groq	Free tier available	Fast inference (Llama, Mixtral)
Cerebras	Free tier available	Fast inference (Llama, Qwen, etc.)
LongCat	Free: up to 5M tokens/day	Fast inference
ModelScope	Free: 2000 requests/day	Inference (Qwen, GLM, DeepSeek, etc.)

---