Bài viết này trình bày các tham số mới và lưu ý sử dụng cho Kimi K3. Trên AIHubMix, K3 có sẵn qua các API Chat Completions, Responses và Messages tương thích Claude. Xem thêm: tài liệu chính thức của nền tảng Moonshot.
Các kết luận "Verified" và phản hồi mẫu trong mỗi phần đến từ các lệnh gọi thực tế được thực hiện vào ngày 17/07/2026 qua các API của AIHubMix (Chat Completions / Responses / Messages).
1. Thông số mô hình tổng quan
| Mục | Giá trị |
|---|---|
| Cửa sổ ngữ cảnh | 1M token |
| Đầu ra tối đa | max_completion_tokens mặc định là 131,072, tối đa 1,048,576 |
| Loại đầu vào | Văn bản, hình ảnh (về đầu vào video, xem tài liệu chính thức của Moonshot) |
| Chế độ thinking | Bật mặc định; reasoning_effort chỉ hỗ trợ "max" |
| Chuỗi dừng | stop cho phép tối đa 5 mục, mỗi mục không quá 32 byte |
Verified: cả hai giới hạn củastopđều được kiểm tra, và vượt quá một trong hai sẽ trả về 400; API Messages áp dụng cùng cơ chế kiểm tra chostop_sequences.
❗ Khi gặp chuỗi dừng, API Messages không tuân theo ngữ nghĩa của Anthropic: trong quá trình thử nghiệm,stop_reasonlà"end_turn"(thay vì"stop_sequence"),stop_sequencelànull, và phần văn bản hiển thị trước từ dừng có thể rỗng. Các client dựa vào hai trường này để phát hiện cắt cụt cần lưu ý điều này.
# stop with 6 entries / a 33-byte entry -> HTTP 400
"Invalid request: stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead"
"Invalid request: stop sequence must not be longer than 32, but got 33 instead"
2. Chế độ Thinking: reasoning_effort chỉ hỗ trợ max
Thinking của K3 được bật mặc định, và reasoning_effort chỉ hỗ trợ một mức duy nhất: "max".
Các cuộc hội thoại nhiều lượt phải truyền lại nguyên văn lịch sử thinking: theo tài liệu chính thức của Moonshot, K3 được huấn luyện với cơ chế giữ lại thinking, vì vậy trong hội thoại nhiều lượt, tin nhắn assistant trước đó phải được truyền lại đầy đủ và không chỉnh sửa (bao gồm nội dung thinking). Thiếu lịch sử thinking sẽ dẫn đến chất lượng đầu ra không ổn định. Nếu bạn dùng framework quản lý phiên hoặc lớp proxy, hãy xác nhận nội dung thinking được truyền lại nguyên vẹn.
Chat Completions
Nội dung thinking được trả về trong trường reasoning_content của phản hồi; trong hội thoại nhiều lượt, hãy truyền lại nguyên văn tin nhắn assistant trước đó (bao gồm reasoning_content).
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
api_key="<AIHUBMIX_API_KEY>",
)
completion = client.chat.completions.create(
model="kimi-k3",
reasoning_effort="max",
messages=[
{"role": "user", "content": "A snail is at the bottom of a 10-meter well. Each day it climbs 3 meters, but each night it slides back 2 meters. How many days does it take to reach the top?"}
],
)
print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
# Multi-turn: pass the previous assistant message back verbatim
messages = [
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris.", "reasoning_content": "<reasoning_content from the previous response>"},
{"role": "user", "content": "And its population?"},
]
Verified: phản hồi trả vềreasoning_content; sau khi truyền lại nguyên văn tin nhắn assistant trước đó (bao gồmreasoning_content), các lượt tiếp theo trả lời bình thường.
Responses
Nội dung thinking được trả về dưới dạng mục đầu ra reasoning; trong hội thoại nhiều lượt, hãy nối các mục đầu ra của lượt trước (reasoning + message) trở lại input nguyên văn.
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
api_key="<AIHUBMIX_API_KEY>",
)
response = client.responses.create(
model="kimi-k3",
input="Answer in one word: capital of France",
)
# Observed response.output item types: ["reasoning", "message"]; text: "Paris"
# Multi-turn: input = [first user message] + response.output + [next user message]
# Observed second-turn answer with output items passed back: "Berlin"
Messages
Nội dung thinking được trả về dưới dạng các khối nội dung thinking gốc; trong hội thoại nhiều lượt, hãy truyền lại nguyên văn các khối nội dung assistant trước đó (bao gồm các khối thinking).
from anthropic import Anthropic
client = Anthropic(
api_key="<AIHUBMIX_API_KEY>",
base_url="https://aihubmix.com"
)
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
messages=[
{"role": "user", "content": "Answer in one word: capital of France"}
],
)
# Observed response.content block types: ["thinking", "text"]; text: "Paris"
# Multi-turn: pass response.content back verbatim as the assistant message
3. Tham số lấy mẫu được cố định
Các tham số lấy mẫu của K3 do nhà cung cấp mô hình cố định: temperature 1.0, top_p 0.95, n 1, và presence_penalty / frequency_penalty 0. Khuyến nghị chính thức là không đưa các tham số này vào yêu cầu.
Lưu ý: các giá trị lấy mẫu cố định là một phần của thông số chính thức và không thể xác minh qua tín hiệu phản hồi; hãy làm theo khuyến nghị chính thức và bỏ qua các tham số này.
4. Gọi công cụ và tải công cụ động
tools hỗ trợ tối đa 128 công cụ; tool_choice hỗ trợ buộc gọi và vô hiệu hóa gọi công cụ. K3 cũng hỗ trợ tải công cụ động: chèn công cụ mới giữa hội thoại thông qua trường tools của tin nhắn system (một cấu trúc tin nhắn riêng của Chat API).
Chat Completions
tool_choice hỗ trợ auto / none / required; required buộc mô hình gọi một công cụ. Tải công cụ động: tin nhắn system dùng để chèn công cụ không có content, các công cụ được chèn sẽ có hiệu lực từ các lượt tiếp theo, và tin nhắn này phải được đưa vào lại trong mọi yêu cầu.
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello."},
{"role": "assistant", "content": "Hi, how can I help you?"},
# Inject a new tool mid-conversation: tools field only, no content
{
"role": "system",
"tools": [
{
"type": "function",
"function": {
"name": "get_time",
"description": "Get the current time",
"parameters": {"type": "object", "properties": {}},
},
}
],
},
{"role": "user", "content": "What time is it now?"},
]
# tool_choice="required" with prompt "Hello" -> the model is forced to call the tool
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]
Verified:tool_choice: "required"buộc gọi công cụ ngay cả với các prompt không liên quan;"none"ngăn gọi công cụ; các công cụ được chèn giữa hội thoại qua tin nhắn system không cócontentcó thể được gọi bình thường.
Responses
Định nghĩa công cụ dùng cấu trúc phẳng (name ở cấp cao nhất); buộc gọi cũng dùng tool_choice: "required", và các lệnh gọi được trả về dưới dạng mục đầu ra function_call. Hỗ trợ tải công cụ động đang được phát triển; hiện tại, hãy khai báo tất cả công cụ trong tham số tools ở cấp cao nhất.
response = client.responses.create(
model="kimi-k3",
input="Hello",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get weather for a city",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice="required",
)
# Observed output contains: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}
Messages
Công cụ dùng định dạng của Anthropic (input_schema); buộc gọi bằng tool_choice: {"type": "any"} và vô hiệu hóa gọi bằng {"type": "none"}. ❗ Endpoint Messages (tương thích Anthropic) chính thức của Kimi K3 không hỗ trợ tải công cụ động: trong quá trình thử nghiệm, tin nhắn chèn công cụ trả về 200, nhưng công cụ được chèn không có tác dụng (mô hình không thể gọi nó). Hãy khai báo tất cả công cụ trong tham số tools ở cấp cao nhất.
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
tools=[{
"name": "get_weather",
"description": "Get weather for a city",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice={"type": "any"},
messages=[{"role": "user", "content": "Hello"}],
)
# Observed: stop_reason "tool_use"; content contains a tool_use block calling get_weather
5. Đầu ra có cấu trúc
Đầu ra có cấu trúc khiến mô hình trả về nội dung tuân thủ nghiêm ngặt một JSON Schema đã cho.
Chat Completions
response_format hỗ trợ json_schema với chế độ strict.
completion = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "Paris is the capital of France. Extract the city name."}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "extract",
"strict": True,
"schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
},
)
# Observed response content: {"city":"Paris"}
Verified: đầu ra là JSON hợp lệ và tuân thủ schema.
Responses
Đầu ra có cấu trúc được khai báo qua text.format.
response = client.responses.create(
model="kimi-k3",
input="Paris is the capital of France. Extract the city name.",
text={
"format": {
"type": "json_schema",
"name": "extract",
"strict": True,
"schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}
},
)
# Observed output text: {"city":"Paris"}
Messages
❗ Endpoint Messages (tương thích Anthropic) chính thức của Kimi K3 không hỗ trợ đầu ra có cấu trúc: các trường structured output bị bỏ qua một cách im lặng: yêu cầu trả về HTTP 200 với văn bản tự do, không có lỗi hay thông báo dự phòng, và việc phân tích JSON ở phía sau sẽ thất bại. Khi cần đầu ra có cấu trúc, hãy dùng API Chat Completions hoặc Responses.
6. Caching ngữ cảnh là tự động
Context caching của K3 được bật tự động, không cần tham số. Khi một tiền tố dài lặp lại trúng cache, lượng trúng cache được báo cáo trong usage (tên trường khác nhau tùy API). Giá cache được hiển thị ở trang mô hình.
Chat Completions
# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}
Verified: yêu cầu thứ hai với cùng tiền tố dài báo cáo lượt trúng cache trongusage.prompt_tokens_details.cached_tokens.
Responses
# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}
Messages
# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536
7. Hoàn thành tiền tố với partial
Hoàn thành tiền tố khiến mô hình tiếp tục sinh nội dung từ một tiền tố đã cho, phù hợp với việc hoàn thành code và đầu ra có kiểm soát định dạng.
Chat Completions
Truyền "partial": true trong tin nhắn assistant cuối cùng.
messages = [
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,", "partial": True},
]
# Prefix: "Waves fold into foam," -> continuation returned by the model
# salt hangs in the air—
# moon pulls the tide home.
Verified: quá trình sinh tiếp tục từ tiền tố đã cho mà không lặp lại tiền tố.
Responses
Truyền tiền tố như một tin nhắn assistant ở cuối mảng input; không cần tham số partial.
response = client.responses.create(
model="kimi-k3",
input=[
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,"},
],
)
# Observed continuation: "salt hangs in the air— / moon pulls the tide home."
Messages
Cùng khả năng này đạt được bằng cơ chế assistant prefill gốc của giao thức, không cần tham số partial: truyền tiền tố như tin nhắn assistant cuối cùng.
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
messages=[
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,"},
],
)
# Observed continuation: "salt wind carries the gull's cry— / tide pulls ..."
8. Đầu vào hình ảnh
Hình ảnh được truyền dưới dạng base64; định dạng khối nội dung khác nhau tùy API.
Chat Completions
messages = [
{
"role": "user",
"content": [
{"type": "text", "text": "What is the dominant color of this image? One word."},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
],
}
]
# Observed response content: "Red" (input: a 64x64 solid red PNG)
Verified: đầu vào hình ảnh base64 hoạt động, và mô hình mô tả đúng hình ảnh thử nghiệm.
Responses
input = [
{
"role": "user",
"content": [
{"type": "input_text", "text": "What is the dominant color of this image? One word."},
{"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
],
}
]
# Observed output text: "Red"
Messages
messages = [
{
"role": "user",
"content": [
{"type": "text", "text": "What is the dominant color of this image? One word."},
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
],
}
]
# Observed response text: "Red"
9. Tham chiếu đã xác minh: độ trễ và mức sử dụng của một tác vụ dài trong một lệnh gọi
Thinking của K3 được cố định ở mức max, nên các yêu cầu đơn lẻ cho tác vụ phức tạp mất thời gian đáng kể hơn so với các mô hình thông thường. Dữ liệu đo được từ tác vụ tạo một game HTML trong một tệp duy nhất (một prompt kèm hình ảnh tham chiếu, tạo một lần duy nhất không lặp lại): yêu cầu đơn lẻ mất 2,541 giây (khoảng 42 phút), với 74,994 completion token, trong đó 54,486 (73%) là thinking token; đầu ra cuối cùng là 1,275 dòng code chạy được ngay, với finish_reason là stop.
Khuyến nghị phía client:
- Đặt timeout của client ở mức vài phút hoặc lâu hơn, và ưu tiên streaming cho các tác vụ dài;
- Dành đủ dư địa trong
max_completion_tokens: trong trường hợp này, riêng phần thinking đã tiêu tốn 54,486 token.
10. Ma trận hỗ trợ khả năng × API
Mọi ô trong bảng dưới đây được xác minh vào ngày 17/07/2026 qua các lệnh gọi thực tế tới API production của AIHubMix; mỗi ô hiển thị cú pháp tham số / trường tương ứng cho API đó.
| Khả năng | Chat Completions | Responses | Messages |
|---|---|---|---|
| Nội dung thinking trong phản hồi | ✅ trường reasoning_content |
✅ mục đầu ra reasoning |
✅ khối nội dung thinking |
| Truyền lại lịch sử thinking | ✅ tin nhắn assistant truyền lại nguyên văn | ✅ mục đầu ra truyền lại nguyên văn | ✅ khối nội dung truyền lại nguyên văn |
| Buộc / vô hiệu hóa gọi công cụ | ✅ tool_choice: "required" / "none" |
✅ tool_choice: "required" |
✅ {"type": "any"} / {"type": "none"} |
| Tải công cụ động | ✅ tin nhắn system với tools (không có content) |
➖ Đang phát triển hỗ trợ | ❗ Không hỗ trợ trên endpoint Messages (tương thích Anthropic) chính thức |
| Đầu ra có cấu trúc | ✅ response_format (json_schema + strict) |
✅ text.format (json_schema) |
❗ Không hỗ trợ trên endpoint chính thức; các trường bị bỏ qua một cách im lặng (200 + văn bản tự do); hãy dùng Chat / Responses thay thế |
| Đo lường cache-hit tự động | ✅ usage.prompt_tokens_details.cached_tokens |
✅ usage.input_tokens_details.cached_tokens |
✅ usage.cache_read_input_tokens |
| Hoàn thành tiền tố | ✅ "partial": true |
✅ assistant prefill | ✅ assistant prefill (gốc của giao thức) |
| Đầu vào hình ảnh | ✅ image_url (base64) |
✅ input_image (base64) |
✅ khối nội dung image (base64) |
| Chuỗi dừng | ✅ stop (giới hạn đã được kiểm tra) |
➖ Đang phát triển hỗ trợ | ❗ Giới hạn stop_sequences được kiểm tra giống hệt, nhưng khi gặp chuỗi dừng, không trả về stop_reason: "stop_sequence" cũng như giá trị stop_sequence |
Câu hỏi thường gặp
K3 hỗ trợ những API nào trên AIHubMix?
Chat Completions (/v1/chat/completions), Responses (/v1/responses), và API Messages tương thích Claude (/v1/messages).
Có thể tắt hoặc giảm thinking không?
Không. Thinking của K3 được bật mặc định, và reasoning_effort chỉ hỗ trợ duy nhất mức "max".
Vì sao reasoning_content phải được truyền lại trong các cuộc hội thoại nhiều lượt?
K3 được huấn luyện với cơ chế giữ lại quá trình suy luận (preserved thinking); Moonshot yêu cầu tin nhắn assistant trước đó phải được truyền lại đầy đủ và không bị sửa đổi. Nếu thiếu lịch sử suy luận, chất lượng đầu ra sẽ không ổn định.
Giới hạn của tham số stop là gì?
Tối đa 5 chuỗi stop, mỗi chuỗi không dài quá 32 byte; vượt quá một trong hai giới hạn này sẽ trả về lỗi 400.
Messages API có hỗ trợ đầu ra có cấu trúc (structured output) không?
❗ Không. Endpoint Messages chính thức của Kimi K3 (tương thích Anthropic) âm thầm bỏ qua các trường structured output (trả về 200 với văn bản tự do và không có lỗi). Để có structured output, hãy dùng response_format trên Chat Completions hoặc text.format trên Responses.
Vì sao các yêu cầu K3 đơn lẻ mất nhiều thời gian như vậy?
Mức suy luận (thinking) của K3 được cố định ở mức tối đa, và các token suy luận chiếm tỷ lệ lớn trong các tác vụ phức tạp (73% số token completion trong trường hợp đo được). Hãy đặt thời gian chờ (timeout) của client thành vài phút hoặc lâu hơn và sử dụng streaming.
Để xem giá và trạng thái thời gian thực, hãy truy cập trang mô hình Kimi K3; để xem thêm các mô hình khác, hãy truy cập thư viện mô hình.
Cập nhật lần cuối: 2026-07-17
