Skip to content

Build and run agents you can see, understand and trust.

feat(moonshot): support kimi k3.1 pro variants (#3578)

YingchaoX32fe303c7152
diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.py
index d77d55e20..03c35c8a7 100644
--- a/src/agentscope/model/_moonshot/_model.py
+++ b/src/agentscope/model/_moonshot/_model.py
@@ -22,9 +22,20 @@ else:
ChatCompletion = Any
AsyncStream = Any
+_K3_MODELS = {"kimi-k3", "kimi-k3.1-pro", "kimi-k3.1-pro-highspeed"}
+
class MoonshotChatModel(ChatModelBase):
- """The Moonshot AI chat model."""
+ """The Moonshot AI chat model.
+
+ For the Kimi K3 series, thinking is always enabled. Fixed
+ sampling parameters (``temperature``, ``top_p``, ``n``,
+ ``presence_penalty``, ``frequency_penalty``) and ``thinking`` are
+ omitted, including values supplied through ``extra_body``. Call-level
+ reasoning and token budgets override :class:`Parameters`. Token budgets
+ in ``extra_body`` override top-level budgets; within each level,
+ ``max_completion_tokens`` takes precedence over ``max_tokens``.
+ """
class Parameters(BaseModel):
"""The parameters for the Moonshot AI chat model."""
@@ -32,7 +43,10 @@ class MoonshotChatModel(ChatModelBase):
max_tokens: int | None = Field(
default=None,
title="Max Tokens",
- description="The maximum number of tokens for the LLM output.",
+ description=(
+ "The maximum number of tokens for the LLM output. "
+ "Sent as max_completion_tokens for Kimi K3 and K3.1 Pro."
+ ),
gt=0,
)
@@ -44,7 +58,8 @@ class MoonshotChatModel(ChatModelBase):
"thinking is always enabled. For kimi-k2.6, thinking is "
"enabled by default but can be disabled. When None, no "
"``thinking`` option is sent and the model's default "
- "behavior applies."
+ "behavior applies. "
+ "Ignored for the Kimi K3 series, which always thinks."
),
)
@@ -52,7 +67,7 @@ class MoonshotChatModel(ChatModelBase):
default=None,
title="Reasoning Effort",
description=(
- "The reasoning effort level for kimi-k3. "
+ "The reasoning effort level for Kimi K3 and K3.1 Pro. "
"Supports 'low', 'high', and 'max' "
"(default 'max')."
),
@@ -95,7 +110,8 @@ class MoonshotChatModel(ChatModelBase):
credential (`MoonshotCredential`):
The Moonshot AI credential used to authenticate API calls.
model (`str`):
- The model name, e.g. ``moonshot-v1-8k``, ``kimi-k2.6``.
+ The model name, e.g. ``moonshot-v1-8k``, ``kimi-k3.1-pro``,
+ or ``kimi-k3.1-pro-highspeed``.
parameters (`MoonshotChatModel.Parameters | None`, defaults to \
`None`):
The API parameters. When ``None``, the default parameters
@@ -191,13 +207,10 @@ class MoonshotChatModel(ChatModelBase):
"stream": self.stream,
}
- is_k3 = model_name == "kimi-k3"
+ is_k3 = model_name in _K3_MODELS
if self.parameters.max_tokens is not None:
- if is_k3:
- kwargs["max_completion_tokens"] = self.parameters.max_tokens
- else:
- kwargs["max_tokens"] = self.parameters.max_tokens
+ kwargs["max_tokens"] = self.parameters.max_tokens
if self.parameters.temperature is not None:
kwargs["temperature"] = self.parameters.temperature
@@ -205,12 +218,12 @@ class MoonshotChatModel(ChatModelBase):
if self.parameters.top_p is not None:
kwargs["top_p"] = self.parameters.top_p
+ if is_k3 and self.parameters.reasoning_effort is not None:
+ kwargs["reasoning_effort"] = self.parameters.reasoning_effort
+
kwargs.update(generate_kwargs)
- if is_k3:
- if self.parameters.reasoning_effort is not None:
- kwargs["reasoning_effort"] = self.parameters.reasoning_effort
- elif self.parameters.thinking_enable is not None:
+ if not is_k3 and self.parameters.thinking_enable is not None:
thinking_type = (
"enabled" if self.parameters.thinking_enable else "disabled"
)
@@ -224,6 +237,37 @@ class MoonshotChatModel(ChatModelBase):
},
}
+ if is_k3:
+ if "max_tokens" in kwargs:
+ kwargs.setdefault(
+ "max_completion_tokens",
+ kwargs.pop("max_tokens"),
+ )
+ # The API fixes these settings. Copy extra_body before filtering
+ # so SDK-level overrides cannot reintroduce them or mutate input.
+ omitted = {
+ "temperature",
+ "top_p",
+ "n",
+ "presence_penalty",
+ "frequency_penalty",
+ "thinking",
+ }
+ for key in omitted:
+ kwargs.pop(key, None)
+ if isinstance(kwargs.get("extra_body"), dict):
+ kwargs["extra_body"] = {
+ key: value
+ for key, value in kwargs["extra_body"].items()
+ if key not in omitted
+ }
+ extra_body = kwargs["extra_body"]
+ if "max_tokens" in extra_body:
+ extra_body.setdefault(
+ "max_completion_tokens",
+ extra_body.pop("max_tokens"),
+ )
+
fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
if fmt_tools:
@@ -428,8 +472,9 @@ class MoonshotChatModel(ChatModelBase):
When ``tool_choice.tools`` is specified the schemas list is filtered
to only those tools. When ``tool_choice.mode`` is a specific tool name
- (str) the model is forced to call exactly that tool without needing to
- filter the list, preserving prompt-cache efficiency.
+ (str), K3 models receive only that tool with ``required`` because
+ named tool choice is incompatible with always-on thinking. Other
+ models receive a named tool choice without filtering the list.
Args:
tools (`list[dict] | None`, optional):
@@ -453,12 +498,18 @@ class MoonshotChatModel(ChatModelBase):
mode = tool_choice.mode
if mode not in _TOOL_CHOICE_LITERAL_MODES:
+ if self.model in _K3_MODELS and tools:
+ return [
+ tool for tool in tools if tool["function"]["name"] == mode
+ ], "required"
return tools, {"type": "function", "function": {"name": mode}}
return tools, mode
def _get_disable_thinking_kwargs(self) -> dict:
- """Moonshot uses ``thinking.type=disabled`` in extra_body."""
+ """Skip the disable-thinking fallback for the K3 series."""
+ if self.model in _K3_MODELS:
+ return {}
return {
"extra_body": {"thinking": {"type": "disabled"}},
}
diff --git a/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro-highspeed.yaml b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro-highspeed.yaml
new file mode 100644
index 000000000..7881429a7
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro-highspeed.yaml
@@ -0,0 +1,33 @@
+name: kimi-k3.1-pro-highspeed
+label: Kimi K3.1 Pro Highspeed
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+ - video/mp4
+ - video/mpeg
+ - video/quicktime
+ - video/avi
+ - video/webm
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1048576
+output_size: 1048576
+
+parameter_overrides:
+ max_tokens:
+ maximum: 1048576
+ thinking_enable:
+ hidden: true
+ temperature:
+ hidden: true
+ top_p:
+ hidden: true
diff --git a/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro.yaml b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro.yaml
new file mode 100644
index 000000000..6c8fd9efb
--- /dev/null
+++ b/src/agentscope/model/_moonshot/_models/kimi-k3.1-pro.yaml
@@ -0,0 +1,33 @@
+name: kimi-k3.1-pro
+label: Kimi K3.1 Pro
+status: active
+
+input_types:
+ - text/plain
+ - application/x-thinking
+ - image/jpeg
+ - image/png
+ - image/gif
+ - image/webp
+ - video/mp4
+ - video/mpeg
+ - video/quicktime
+ - video/avi
+ - video/webm
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 1048576
+output_size: 1048576
+
+parameter_overrides:
+ max_tokens:
+ maximum: 1048576
+ thinking_enable:
+ hidden: true
+ temperature:
+ hidden: true
+ top_p:
+ hidden: true
diff --git a/src/agentscope/model/_moonshot/_models/kimi-k3.yaml b/src/agentscope/model/_moonshot/_models/kimi-k3.yaml
index 71dd5cf1f..3c85cc874 100644
--- a/src/agentscope/model/_moonshot/_models/kimi-k3.yaml
+++ b/src/agentscope/model/_moonshot/_models/kimi-k3.yaml
@@ -27,3 +27,7 @@ parameter_overrides:
maximum: 1048576
thinking_enable:
hidden: true
+ temperature:
+ hidden: true
+ top_p:
+ hidden: true
diff --git a/tests/model_moonshot_test.py b/tests/model_moonshot_test.py
index 57208061b..a508efb95 100644
--- a/tests/model_moonshot_test.py
+++ b/tests/model_moonshot_test.py
@@ -4,19 +4,26 @@
Tests cover both non-streaming and streaming modes.
"""
+from copy import deepcopy
+from dataclasses import asdict
+import json
from typing import Any
import unittest
from unittest import IsolatedAsyncioTestCase
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, call
+
+import httpx
from utils import AnyString
-from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
-from agentscope.model import MoonshotChatModel
+from agentscope.exception import StructuredOutputError
+from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock, UserMsg
+from agentscope.model import MoonshotChatModel, StructuredResponse
from agentscope.credential import MoonshotCredential
from agentscope.tool import ToolChoice
A = AnyString()
+_K3_MODELS = ("kimi-k3", "kimi-k3.1-pro", "kimi-k3.1-pro-highspeed")
# ---------------------------------------------------------------------------
@@ -690,3 +697,505 @@ class TestMoonshotFormatTools(unittest.TestCase):
fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)
self.assertEqual(fmt_tools, _FT_TOOLS)
self.assertIsNone(fmt_choice)
+
+
+class MoonshotK3Test(IsolatedAsyncioTestCase):
+ """Verify the shared request contract for the K3 series."""
+
+ async def test_request_parameters(self) -> None:
+ """Translate budgets, preserve overrides, and omit fixed settings."""
+ cases: list[tuple[dict[str, Any], dict[str, Any], dict[str, Any]]] = [
+ ({}, {}, {}),
+ ({"max_tokens": 1024}, {}, {"max_completion_tokens": 1024}),
+ (
+ {"max_tokens": 1024},
+ {"max_tokens": 2048},
+ {"max_completion_tokens": 2048},
+ ),
+ (
+ {"max_tokens": 1024},
+ {"max_completion_tokens": 4096},
+ {"max_completion_tokens": 4096},
+ ),
+ (
+ {"max_tokens": 1024},
+ {"max_tokens": 2048, "max_completion_tokens": 4096},
+ {"max_completion_tokens": 4096},
+ ),
+ (
+ {},
+ {"max_tokens": 1048576},
+ {"max_completion_tokens": 1048576},
+ ),
+ (
+ {
+ "temperature": 0.2,
+ "top_p": 0.4,
+ "thinking_enable": False,
+ },
+ {},
+ {},
+ ),
+ ({"thinking_enable": True}, {}, {}),
+ (
+ {},
+ {
+ "temperature": 1.0,
+ "top_p": 0.95,
+ "n": 1,
+ "presence_penalty": 0,
+ "frequency_penalty": 0,
+ },
+ {},
+ ),
+ (
+ {},
+ {
+ "temperature": 0.2,
+ "top_p": 0.4,
+ "n": 2,
+ "presence_penalty": 1,
+ "frequency_penalty": 1,
+ "thinking": {"type": "disabled"},
+ },
+ {},
+ ),
+ (
+ {},
+ {
+ "extra_body": {
+ "temperature": 0.2,
+ "top_p": 0.4,
+ "n": 2,
+ "presence_penalty": 1,
+ "frequency_penalty": 1,
+ "thinking": {"type": "disabled"},
+ "prompt_cache_options": {"ttl": "1h"},
+ },
+ },
+ {"extra_body": {"prompt_cache_options": {"ttl": "1h"}}},
+ ),
+ ]
+ for effort in ("low", "high", "max"):
+ cases.extend(
+ [
+ (
+ {"reasoning_effort": effort},
+ {},
+ {"reasoning_effort": effort},
+ ),
+ (
+ {"reasoning_effort": "max"},
+ {"reasoning_effort": effort},
+ {"reasoning_effort": effort},
+ ),
+ ],
+ )
+ for name in _K3_MODELS:
+ model = _make_model()
+ model.model = name
+ create = AsyncMock(return_value=_mock_completion(text="OK"))
+ model.client.chat.completions.create = create
+ for parameters, kwargs, expected in cases:
+ with self.subTest(
+ model=name,
+ parameters=parameters,
+ kwargs=kwargs,
+ ):
+ model.parameters = MoonshotChatModel.Parameters(
+ **parameters,
+ )
+ original = deepcopy(kwargs)
+ await model([], **kwargs)
+ self.assertDictEqual(
+ create.call_args.kwargs,
+ {
+ "model": name,
+ "messages": [],
+ "stream": False,
+ **expected,
+ },
+ )
+ self.assertDictEqual(kwargs, original)
+ await model.client.close()
+
+ async def test_extra_body_budget_http_request(self) -> None:
+ """Normalize budgets before the SDK merges the final HTTP body."""
+ cases: list[
+ tuple[int | None, dict[str, int], dict[str, int], dict[str, int]]
+ ] = [
+ (None, {}, {}, {}),
+ (None, {}, {"max_tokens": 2048}, {"max_completion_tokens": 2048}),
+ (1024, {}, {}, {"max_completion_tokens": 1024}),
+ (1024, {}, {"max_tokens": 2048}, {"max_completion_tokens": 2048}),
+ (
+ 1024,
+ {},
+ {"max_completion_tokens": 2048},
+ {"max_completion_tokens": 2048},
+ ),
+ (
+ 1024,
+ {"max_tokens": 4096},
+ {"max_tokens": 2048},
+ {"max_completion_tokens": 2048},
+ ),
+ (
+ 1024,
+ {"max_completion_tokens": 4096},
+ {"max_tokens": 2048},
+ {"max_completion_tokens": 2048},
+ ),
+ (
+ 1024,
+ {"max_tokens": 4096, "max_completion_tokens": 8192},
+ {"max_tokens": 2048, "max_completion_tokens": 3072},
+ {"max_completion_tokens": 3072},
+ ),
+ ]
+ bodies: list[dict] = []
+
+ def handle(request: httpx.Request) -> httpx.Response:
+ body = json.loads(request.content)
+ bodies.append(body)
+ if body["stream"]:
+ return httpx.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text="data: [DONE]\n\n",
+ )
+ return httpx.Response(
+ 200,
+ json={
+ "id": "kimi-1",
+ "created": 0,
+ "model": body["model"],
+ "object": "chat.completion",
+ "choices": [
+ {
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": "OK"},
+ },
+ ],
+ },
+ )
+
+ for name in _K3_MODELS:
+ for stream in (False, True):
+ model = MoonshotChatModel(
+ credential=MoonshotCredential(api_key="test"),
+ model=name,
+ stream=stream,
+ client_kwargs={
+ "http_client": httpx.AsyncClient(
+ transport=httpx.MockTransport(handle),
+ ),
+ },
+ )
+ self.addAsyncCleanup(model.client.close)
+ for budget, kwargs, extra_budget, expected in cases:
+ with self.subTest(
+ model=name,
+ stream=stream,
+ budget=budget,
+ kwargs=kwargs,
+ extra_budget=extra_budget,
+ ):
+ model.parameters = MoonshotChatModel.Parameters(
+ max_tokens=budget,
+ )
+ extra_body = {
+ **extra_budget,
+ "prompt_cache_options": {"ttl": "1h"},
+ "temperature": 0.2,
+ "thinking": {"type": "disabled"},
+ }
+ original = deepcopy(extra_body)
+ bodies.clear()
+ response = await model(
+ [],
+ extra_body=extra_body,
+ **kwargs,
+ )
+ if stream:
+ async for _ in response:
+ pass
+ self.assertEqual(
+ bodies,
+ [
+ {
+ "model": name,
+ "messages": [],
+ "stream": stream,
+ "prompt_cache_options": {"ttl": "1h"},
+ **expected,
+ **(
+ {
+ "stream_options": {
+ "include_usage": True,
+ },
+ }
+ if stream
+ else {}
+ ),
+ },
+ ],
+ )
+ self.assertEqual(extra_body, original)
+
+ async def test_legacy_request_parameters(self) -> None:
+ """Existing models keep their sampling and thinking behavior."""
+ for name in (
+ "kimi-k2.6",
+ "kimi-k2.7-code",
+ "kimi-k2.7-code-highspeed",
+ "moonshot-v1-8k",
+ ):
+ with self.subTest(model=name):
+ model = _make_model()
+ model.model = name
+ model.parameters = MoonshotChatModel.Parameters(
+ max_tokens=1024,
+ reasoning_effort="high",
+ temperature=0.2,
+ top_p=0.4,
+ )
+ create = AsyncMock(return_value=_mock_completion(text="OK"))
+ model.client.chat.completions.create = create
+ await model([])
+ expected = {
+ "model": name,
+ "messages": [],
+ "stream": False,
+ "temperature": 0.2,
+ "top_p": 0.4,
+ "max_tokens": 1024,
+ }
+ self.assertDictEqual(create.call_args.kwargs, expected)
+ self.assertDictEqual(
+ model._get_disable_thinking_kwargs(),
+ {
+ "extra_body": {
+ "thinking": {"type": "disabled"},
+ },
+ },
+ )
+ await model.client.close()
+
+ async def test_structured_output_skips_disable_thinking(self) -> None:
+ """The real fallback ladder must not attempt to turn thinking off."""
+ for name in _K3_MODELS:
+ with self.subTest(model=name):
+ model = _make_model()
+ model.model = name
+ messages = [UserMsg("user", "Return an answer")]
+ schema = {"type": "object"}
+ attempt = AsyncMock(
+ side_effect=[
+ StructuredOutputError("try auto"),
+ StructuredOutputError("try unforced"),
+ StructuredResponse(content={"answer": 42}),
+ ],
+ )
+ model._call_api_with_structured_output = attempt
+ result = await model.generate_structured_output(
+ messages,
+ schema,
+ )
+ self.assertDictEqual(
+ asdict(result),
+ {
+ "content": {"answer": 42},
+ "usage": None,
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "type": "structured_response",
+ "metadata": {},
+ "finished_reason": "completed",
+ },
+ )
+ self.assertListEqual(
+ attempt.call_args_list,
+ [
+ call(
+ name,
+ messages=messages,
+ structured_model=schema,
+ tool_choice=ToolChoice(
+ mode="generate_structured_output",
+ ),
+ ),
+ call(
+ name,
+ messages=messages,
+ structured_model=schema,
+ tool_choice=ToolChoice(mode="auto"),
+ ),
+ call(
+ name,
+ messages=messages,
+ structured_model=schema,
+ tool_choice=None,
+ ),
+ ],
+ )
+ await model.client.close()
+
+ async def test_named_tool_request(self) -> None:
+ """Force only the selected tool without mutating caller schemas."""
+ for name in _K3_MODELS:
+ with self.subTest(model=name):
+ model = _make_model()
+ self.addAsyncCleanup(model.client.close)
+ model.model = name
+ create = AsyncMock(return_value=_mock_completion(text="OK"))
+ model.client.chat.completions.create = create
+ tools = deepcopy(_FT_TOOLS)
+ await model(
+ [],
+ tools=tools,
+ tool_choice=ToolChoice(mode="get_weather"),
+ )
+ self.assertDictEqual(
+ create.call_args.kwargs,
+ {
+ "model": name,
+ "messages": [],
+ "stream": False,
+ "tools": [_FT_TOOLS[0]],
+ "tool_choice": "required",
+ },
+ )
+ self.assertEqual(tools, _FT_TOOLS)
+
+ async def test_structured_output_uses_required(self) -> None:
+ """Generate structured output on the first API request."""
+ schema = {
+ "type": "object",
+ "properties": {"answer": {"type": "integer"}},
+ "required": ["answer"],
+ }
+ for name in _K3_MODELS:
+ with self.subTest(model=name):
+ model = _make_model()
+ self.addAsyncCleanup(model.client.close)
+ model.model = name
+ create = AsyncMock(
+ return_value=_mock_completion(
+ tool_calls=[
+ {
+ "id": "call-1",
+ "name": "generate_structured_output",
+ "arguments": '{"answer": 42}',
+ },
+ ],
+ ),
+ )
+ model.client.chat.completions.create = create
+ result = await model.generate_structured_output(
+ [UserMsg("user", "Return an answer")],
+ schema,
+ )
+ self.assertEqual(result.content, {"answer": 42})
+ create.assert_awaited_once()
+ self.assertEqual(
+ (
+ create.call_args.kwargs["tool_choice"],
+ create.call_args.kwargs["tools"],
+ ),
+ (
+ "required",
+ [
+ {
+ "type": "function",
+ "function": {
+ "name": "generate_structured_output",
+ "description": "Call this function to "
+ "generate structured output required "
+ "by the user.",
+ "parameters": schema,
+ },
+ },
+ ],
+ ),
+ )
+
+ def test_model_cards(self) -> None:
+ """All K3 models expose consistent capabilities and parameters."""
+ cards = {card.name: card for card in MoonshotChatModel.list_models()}
+ labels = {
+ "kimi-k3": "Kimi K3",
+ "kimi-k3.1-pro": "Kimi K3.1 Pro",
+ "kimi-k3.1-pro-highspeed": "Kimi K3.1 Pro Highspeed",
+ }
+ for name in _K3_MODELS:
+ with self.subTest(model=name):
+ self.assertIn(name, cards)
+ self.assertDictEqual(
+ cards[name].model_dump(),
+ {
+ "type": "chat_model",
+ "model_class": "moonshot_chat",
+ "name": name,
+ "label": labels[name],
+ "status": "active",
+ "deprecated_at": None,
+ "input_types": [
+ "text/plain",
+ "application/x-thinking",
+ "image/jpeg",
+ "image/png",
+ "image/gif",
+ "image/webp",
+ "video/mp4",
+ "video/mpeg",
+ "video/quicktime",
+ "video/avi",
+ "video/webm",
+ ],
+ "output_types": [
+ "text/plain",
+ "application/x-thinking",
+ ],
+ "context_size": 1048576,
+ "output_size": 1048576,
+ "parameters_overrides": {
+ "max_tokens": {"maximum": 1048576},
+ "thinking_enable": {"hidden": True},
+ "temperature": {"hidden": True},
+ "top_p": {"hidden": True},
+ },
+ "parameter_schema": {
+ "type": "object",
+ "required": [],
+ "properties": {
+ "max_tokens": {
+ "anyOf": [
+ {
+ "exclusiveMinimum": 0,
+ "type": "integer",
+ },
+ {"type": "null"},
+ ],
+ "default": None,
+ "title": "Max Tokens",
+ "description": AnyString(),
+ "maximum": 1048576,
+ },
+ "reasoning_effort": {
+ "anyOf": [
+ {
+ "enum": ["low", "high", "max"],
+ "type": "string",
+ },
+ {"type": "null"},
+ ],
+ "default": None,
+ "title": "Reasoning Effort",
+ "description": AnyString(),
+ },
+ },
+ },
+ },
+ )