如何在 Swarms 中上手 Kimi K3：分步教程

月之暗面（Moonshot AI）的 Kimi K3 是一款推理能力强、成本可控的模型，而 Swarms 框架 是把它变成可用智能体的最快方式。在本教程中，你将用 uv 安装 Swarms，运行单个 Kimi K3 智能体，用 Ollama 在本地跑同一个模型，然后把多个 Kimi 智能体接入一个 GroupChat，让它们围绕同一个问题展开讨论并得出结论。无需任何智能体开发经验，全程大约五分钟。

第一步：安装 Swarms

用 uv 创建项目并安装 Swarms：

uv init kimi-swarms && cd kimi-swarms
uv add swarms

就这么简单：uv add swarms 会在几秒内解析并安装框架及其全部依赖。如果你更习惯用 pip，执行 pip install swarms 同样可行。

第二步：设置 API 密钥

Kimi K3 通过 OpenRouter 提供服务，因此你需要一个 OpenRouter API 密钥。把它保存到项目根目录的 .env 文件中：

echo 'OPENROUTER_API_KEY="sk-or-your-key-here"' > .env

Swarms 会在运行时自动加载，你无需把密钥硬编码进代码。

第三步：运行单个 Kimi K3 智能体

新建 single_agent.py。模型名称是 openrouter/moonshotai/kimi-k3，这个带服务商前缀的字符串就是路由到 Kimi 所需的全部配置：

from dotenv import load_dotenv
from swarms import Agent

load_dotenv()

agent = Agent(
    agent_name="Research-Agent",
    agent_description="A concise research and analysis assistant",
    system_prompt=(
        "You are a sharp research analyst. Answer clearly, cite the key "
        "trade-offs, and state any assumptions you make."
    ),
    model_name="openrouter/moonshotai/kimi-k3",
    max_loops=1,
    reasoning_effort="low",
)

result = agent.run(
    task="Explain the trade-offs between vector databases and keyword search for RAG."
)
print(result)

运行它：

uv run single_agent.py

你已经构建了一个可用的 Kimi K3 智能体。Agent 类会替你处理提示词、模型调用、记忆和输出格式化。每个参数（system_prompt、max_loops、reasoning_effort）都是可调的旋钮，但默认值已经足够合理，可以直接投入使用。

第四步：用 Ollama 在本地运行 Kimi K3

比起托管 API，更想通过 Ollama 来运行 Kimi K3？Swarms 同样支持，而且切换只需要改一行代码，智能体代码完全不用动。

先用 Ollama 拉取并运行模型：

ollama run kimi-k3:cloud

然后把 model_name 换成带 ollama/ 前缀的字符串，让智能体指向它。其余部分与第三步完全一致：

from swarms import Agent

agent = Agent(
    agent_name="Research-Agent",
    agent_description="A concise research and analysis assistant",
    system_prompt=(
        "You are a sharp research analyst. Answer clearly, cite the key "
        "trade-offs, and state any assumptions you make."
    ),
    model_name="ollama/kimi-k3:cloud",   # <- the only change from Step 3
    max_loops=1,
    reasoning_effort="low",
)

result = agent.run(
    task="Explain the trade-offs between vector databases and keyword search for RAG."
)
print(result)

运行它：

uv run local_agent.py

这正是 model_name 这个字段的威力所在：你的智能体逻辑、工具和编排方式全都不用变，只要换一个字符串，就能在 OpenRouter、Ollama 以及 Swarms 支持的其他数百家服务商之间切换。你可以对着本地模型做开发，再切到托管模型上线，全程不用改动任何一行智能体代码。

第五步：搭建一个 Kimi 智能体 GroupChat

单个智能体负责回答问题，而 GroupChat 能让多个智能体讨论一个问题。每个智能体都有自己的角色设定，会倾听其他成员的发言，并自行决定何时插话。这是针对复杂问题快速获取多方视角的最简路径。

新建 group_chat.py：

from dotenv import load_dotenv
from swarms import Agent
from swarms.structs.groupchat import GroupChat

load_dotenv()

MODEL = "openrouter/moonshotai/kimi-k3"

optimist = Agent(
    agent_name="Optimist",
    system_prompt="You argue for the opportunities and upside.",
    model_name=MODEL,
    max_loops=1,
    persistent_memory=False,
)

skeptic = Agent(
    agent_name="Skeptic",
    system_prompt="You stress-test claims and surface the risks.",
    model_name=MODEL,
    max_loops=1,
    persistent_memory=False,
)

realist = Agent(
    agent_name="Realist",
    system_prompt="You weigh both sides and push for a decision.",
    model_name=MODEL,
    max_loops=1,
    persistent_memory=False,
)

chat = GroupChat(
    name="Kimi Roundtable",
    agents=[optimist, skeptic, realist],
    max_loops=6,
)

result = chat.run(
    "Should an early-stage startup build its own agents or buy a platform?"
)
print(result)

运行它：

uv run group_chat.py

三个 Kimi K3 智能体现在会实时辩论这个问题。注意所需的接线有多少：你定义了三个角色，把它们放进 GroupChat，然后调用 run()。发言者选择、消息传递和停止条件都由 Swarms 处理，max_loops 则为对话轮数设置上限。GroupChat 还会自动为每个智能体配置好参与讨论所需的能力，无需额外挂载工具。

你学到了什么，以及下一步

短短几分钟内，你用 uv 安装了 Swarms，运行了单个 Kimi K3 智能体，并编排了一个多智能体 GroupChat，这两块正是几乎所有智能体应用的基础构件。这套模式可以持续扩展：把 GroupChat 换成 SequentialWorkflow、ConcurrentWorkflow 或 HierarchicalSwarm，智能体本身不用改动，改变的只是编排方式。接下来，可以给智能体挂上工具（任何带 docstring 的 Python 函数都能被调用），也可以混用模型，把 Kimi K3 与 GPT 或 Claude 智能体放进同一个蜂群，并进一步查阅 Swarms 文档 和 GitHub 上的示例。

Kimi K3 以低廉的价格提供了强大的推理能力，Swarms 则提供了让它真正干活的编排能力。先从上面的单个智能体开始，然后让你的 Kimi 智能体彼此对话。

结论

三个文件、不到一百行 Python 代码，就把你从一个空目录带到了一个可运行的多智能体系统。这正是这套技术栈的意义所在：Kimi K3 提供强大的推理能力，且价格低到让你可以放心地同时跑多个智能体；Swarms 提供编排能力，让你不必手写消息传递、发言者选择和结果收集。

这里最值得记住的一点是：智能体本身与编排方式是两件相互独立的事。你那四个 Agent 定义在第三步和第五步之间没有任何改动，变的只是包在外面的那一层；同样地，第四步换到 Ollama 时，改动的也只有一个模型名字符串。正是这种解耦，让你可以先从单个智能体起步，在需要多方视角时加上 GroupChat，之后再换成 SequentialWorkflow 或 HierarchicalSwarm，而完全不用重写智能体本身。

接下来，收益最高的几个方向是：给智能体挂上工具（任何带 docstring 的 Python 函数都能被调用）；混用模型，让便宜的智能体起草、更强的智能体复审；以及围绕你自己的延迟和成本目标去调优 max_loops 和 reasoning_effort。下面的示例仓库是最快看到这些模式的可运行代码的地方。

相关链接与资源

---

有问题或反馈？欢迎加入我们的 Discord 社区，或查阅 官方文档。