企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• 代码智能体

本指南以mini-swe-agent（一个仅约百行核心代码、可在 SWE-bench Verified 上取得高分并用于命令行辅助编程的 AI Agent）为背景，系统讲解其模型接入与配置的全部要点：如何设置 API Key、如何选择默认模型、如何通过 agent 配置文件的model段落精调 temperature、reasoning effort 等参数，以及litellm、litellm_response、openrouter、portkey等多种模型后端类的适用场景。读完本指南，你将能够独立完成从零配置到按需切换任意模型后端的完整实战部署。

快速上手：一条命令完成模型与 API Key 配置

绝大多数场景下，你不需要手工编辑任何配置文件。mini-swe-agent提供了一条交互式配置命令，推荐在首次运行mini之前执行：

mini-extra config setup

该命令会引导你完成两步操作：

1. 设置默认模型：输入类似anthropic/claude-opus-4-6-20260205这样的完整模型名（务必带上 provider 前缀，详见下文“选择模型”一节）；
2. 设置 API Key：输入密钥名称（如ANTHROPIC_API_KEY）和密钥值（如sk-...）。

如果不想在首次运行时手动操作，这条命令也会在你第一次执行mini时自动触发——mini会检测环境变量MSWEA_CONFIGURED，若未设置则自动进入配置流程。从源码看，该命令的实际行为由 src/minisweagent/run/utilities/config.py 中的setup()函数实现：它通过dotenv的set_key把MSWEA_MODEL_NAME、MSWEA_CONFIGURED及你指定的 API Key 写入全局配置（.env）文件，随后调用_reload_config()重新加载环境变量使其立即生效。

提示：配置完成、需要修改时，随时可以重新运行mini-extra config setup，或使用下文介绍的config set/config edit命令。

设置 API Key 的四种方式

mini-swe-agent通过环境变量读取模型提供方的密钥。以 Anthropic 为例，以下是四种等效的配置途径，按推荐程度排列：

其中mini-extra config set KEY VALUE、mini-extra config unset KEY与mini-extra config edit三个子命令均由 src/minisweagent/run/utilities/config.py 实现，分别调用dotenv的set_key、unset_key以及系统的文本编辑器，操作完成后都会自动重载配置。

如果你同时并行运行多个 agent 实例，需要注意 Anthropic 等提供方对密钥有调用速率限制。针对这种场景，可以参考 全局配置指南 中关于轮换 Anthropic 密钥的说明来安排多个密钥。

完整的 API Key 名称清单

mini-swe-agent底层通过litellm对接绝大多数模型提供方，因此litellm支持的密钥名称均可直接使用。以下为当前支持的完整清单：

ALEPH_ALPHA_API_KEY ALEPHALPHA_API_KEY ANTHROPIC_API_KEY ANYSCALE_API_KEY AZURE_AI_API_KEY AZURE_API_KEY AZURE_OPENAI_API_KEY BASETEN_API_KEY CEREBRAS_API_KEY CLARIFAI_API_KEY CLOUDFLARE_API_KEY CO_API_KEY CODESTRAL_API_KEY COHERE_API_KEY DATABRICKS_API_KEY DEEPINFRA_API_KEY DEEPSEEK_API_KEY FEATHERLESS_AI_API_KEY FIREWORKS_AI_API_KEY FIREWORKS_API_KEY FIREWORKSAI_API_KEY GEMINI_API_KEY GROQ_API_KEY HUGGINGFACE_API_KEY INFINITY_API_KEY MARITALK_API_KEY MISTRAL_API_KEY NEBIUS_API_KEY NLP_CLOUD_API_KEY NOVITA_API_KEY NVIDIA_NIM_API_KEY OLLAMA_API_KEY OPENAI_API_KEY OPENAI_LIKE_API_KEY OPENROUTER_API_KEY OR_API_KEY PALM_API_KEY PERPLEXITYAI_API_KEY PREDIBASE_API_KEY PROVIDER_API_KEY REPLICATE_API_KEY TOGETHERAI_API_KEY VOLCENGINE_API_KEY VOYAGE_API_KEY WATSONX_API_KEY WX_API_KEY XAI_API_KEY XINFERENCE_API_KEY

此外，如果使用 Portkey 后端，则额外需要PORTKEY_API_KEY环境变量（Portkey 模型的密钥配置见 Portkey 模型参考文档）。

选择默认模型

mini-swe-agent支持litellm支持的绝大多数模型，官方文档建议在模型名中始终包含 provider 前缀，例如anthropic/claude-...，这样litellm才能正确路由到对应的提供方 API。

设置默认模型有四种途径，优先级从高到低为：

1. 命令行参数：所有 CLI 接口均支持-m或--model指定本次运行的模型名；
2. mini-extra config setup：交互式配置会写入MSWEA_MODEL_NAME；
3. 全局配置：通过mini-extra config set MSWEA_MODEL_NAME <model-name>、编辑全局配置文件（快捷键mini-extra config edit）或设置MSWEA_MODEL_NAME环境变量；
4. agent 配置文件：在 YAML 配置文件的model段落下设置model_name键（详见下一节）。

这一优先级顺序可以在源码中得到印证：在 src/minisweagent/models/init.py 的get_model_name()函数中，模型名依次取自命令行传入参数、配置字典中的model_name、环境变量MSWEA_MODEL_NAME，三者皆无时才抛出ValueError，并提示运行mini-extra config setup。

流行的模型示例

以下是一些常见且经过验证的模型名写法（注意litellm的最新模型清单会持续更新，以litellm仓库维护的model_prices_and_context_window.json为准）：

anthropic/claude-opus-4-6-20260205 openai/gpt-5.4 openai/gpt-5.4-mini gemini/gemini-2.5-pro deepseek/deepseek-chat

更多litellm支持的模型名可以参考仓库内的 docs/data/all_models.txt（该项目维护的一份模型名快照）。对照litellm官方 provider 文档即可找到每个模型对应的 API Key 名称——上一节的清单就是答案。

如果你想使用本地部署的模型（如 vLLM、Ollama 等），请阅读专门的 本地模型指南，其中详细说明了custom_llm_provider、api_base以及本地模型 token 成本配置。

精细调参：agent 配置文件中的 model 段落

mini-swe-agent的运行配置基于 YAML 文件（默认配置文件为 src/minisweagent/config/mini.yaml，其中已包含一个带drop_params: true的model_kwargs示例）。要设置 temperature、reasoning effort 等模型专属参数，需要编辑 agent 配置文件中的model段落。在新版本中，运行mini时输出里会打印配置文件的位置（标注为 "agent config"）。

配置文件的完整说明参见 YAML 配置指南，全局环境变量类配置参见 全局配置指南。下面给出几类最常见场景的完整配置示例。

设置 Temperature

litellm允许通过model_kwargs键传递模型专属参数，这些参数会被直接透传给底层litellm.completion()调用。例如：

model: model_name: "anthropic/claude-sonnet-4-5-20250929" model_kwargs: temperature: 0.0

注意：并非所有模型都支持 temperature 参数。对于不支持的模型，可配合drop_params: true让litellm自动丢弃不受支持的参数。

GPT-5 推理强度（Chat Completions API）

对于通过 Chat Completions API 调用的 GPT-5 系列模型，可配置reasoning_effort与verbosity：

model: model_name: "openai/gpt-5-mini" model_kwargs: drop_params: true reasoning_effort: "high" verbosity: "medium"

这里drop_params: true的作用是丢弃该模型不支持的参数，避免因多余参数导致 API 报错。

GPT-5 使用 Responses API

对于支持 OpenAI Responses API 的模型，可以显式指定litellm_response_toolcall模型类，并将推理参数放在reasoning键下：

model: model_class: "litellm_response_toolcall" model_name: "openai/gpt-5-mini" model_kwargs: drop_params: true reasoning: effort: "high"

固定 OpenRouter 提供方

通过openrouter模型类接入 OpenRouter 时，可以显式锁定提供方（provider），避免 OpenRouter 在不同提供方之间自动切换。这适合需要成本行为高度一致的基准测试场景；如果只是追求低延迟和好价格，则不建议锁定：

model: model_name: "moonshotai/kimi-k2-0905" model_class: "openrouter" model_kwargs: temperature: 0.0 provider: allow_fallbacks: false only: ["Moonshot AI"]

本地模型

本地模型同样通过model_kwargs传递custom_llm_provider与api_base：

model: model_name: "my-local-model" model_kwargs: custom_llm_provider: "openai" api_base: "https://..." ...

使用本地模型时，通常还需要处理两件事：一是通过cost_tracking: "ignore_errors"忽略成本计算报错（或配置 litellm 模型注册表提供成本数据），二是可能需要配置LITELLM_MODEL_REGISTRY_PATH。详见 本地模型指南。

更多具体模型的配置示例

以下配置覆盖了不同模型类与提供方的组合，可直接复制到 agent 配置文件中使用：

Gemini 3（OpenRouter）

model: model_name: "google/gemini-3-pro-preview" model_class: openrouter model_kwargs: temperature: 0.0

GPT 5.1 medium（Portkey）

model: model_name: "@openai/gpt-5.1" model_class: portkey model_kwargs: reasoning_effort: "medium" verbosity: "medium"

Claude Haiku 4.5

model: model_name: "anthropic/claude-haiku-4-5-20251001" model_kwargs: temperature: 0.0

GPT 5 mini（Portkey）

model: model_name: "@openai/gpt-5-mini" model_class: portkey

Deepseek

model: model_name: "deepseek/deepseek-reasoner" model_kwargs: temperature: 0.0

Minimax（OpenRouter）

model: model_name: "minimax/minimax-m2" model_class: openrouter model_kwargs: temperature: 0.0

注意 Portkey 模型名的写法带有@前缀（如@openai/gpt-5.1），这是 Portkey 网关路由的模型标识格式。

模型类（Model Classes）：多后端接入机制

mini-swe-agent通过不同的**模型类（model class）**对接不同后端。默认情况下，如果你只指定模型名，框架会自动为你选择最合适的后端——绝大多数场景会落到litellm；Anthropic 模型则是一个特例，因为它需要显式的缓存断点（cache breakpoint）处理，见下文。

从 src/minisweagent/models/init.py 的get_model_class()与_MODEL_CLASS_MAPPING可以看出，模型类既可以通过--model-class命令行参数指定，也可以通过 agent 配置文件的model.model_class键指定，还支持直接写完整的 Python 导入路径。当你显式指定模型类时，它优先于模型名决定后端；未指定时默认回退到LitellmModel。

通过命令行指定模型类

mini -m "moonshotai/kimi-k2-0905" --model-class openrouter

通过配置文件指定模型类

model: model_name: "moonshotai/kimi-k2-0905" model_class: openrouter

Portkey 同理：

mini -m "claude-sonnet-4-5-20250929" --model-class portkey

model: model_name: "claude-sonnet-4-5-20250929" model_class: portkey

各模型类的适用场景

litellm（LitellmModel）—— 默认且推荐。对应源码 src/minisweagent/models/litellm_model.py，通过litellm.completion()调用模型，支持 OpenAI、Anthropic、Google 等几乎所有提供方。当模型名中包含anthropic、claude、sonnet或opus时，框架会自动为其启用缓存控制设置（对应models/__init__.py中的判断逻辑：命中这些关键字且未显式指定set_cache_control时，默认设为"default_end"），帮助降低长上下文调用的成本。其配置类LitellmModelConfig还支持cost_tracking（成本追踪模式）、format_error_template、observation_template、multimodal_regex等进阶选项。详见 LitellmModel 参考文档。

litellm_response（LitellmResponseModel）—— 面向 Responses API 的专门版本。对应源码 src/minisweagent/models/litellm_response_model.py，是LitellmModel的派生类，改用litellm.responses()并原生支持工具调用（native tool calling）。适用于 GPT-5 这类模型，且是 GPT-5-codex 等模型的必需选择；它通过把历史response对象展开为 output items 来跨轮次维护对话状态。详见 LitellmResponseModel 参考文档。

openrouter（OpenRouterModel）—— 直连 OpenRouter API。对应源码 src/minisweagent/models/openrouter_model.py，通过 HTTP 请求访问https://openrouter.ai/api/v1/chat/completions，用OPENROUTER_API_KEY认证，可用一个端点访问多种模型，并区分认证失败（401）、限流（429）与其他 HTTP 错误。详见 OpenRouterModel 参考文档。

portkey（PortkeyModel）—— 接入 Portkey 网关。对应源码 src/minisweagent/models/portkey_model.py，提供更强的可观测性、缓存与路由能力。注意两点：其一，它仍依赖litellm计算成本（支持通过litellm_model_name_override覆盖用于计费的模型名）；其二，使用它需要安装portkey-ai包（pip install portkey-ai），并设置PORTKEY_API_KEY，可选PORTKEY_VIRTUAL_KEY或provider参数。详见 PortkeyModel 参考文档。

更进阶的模型类

除上述生产级后端外，框架还提供两个面向测试与实验的模型类：

• deterministic（DeterministicModel）：返回预定义响应，用于测试与开发阶段的可复现实验。源码位于 src/minisweagent/models/test_models.py。详见 DeterministicModel 参考文档。
• RouletteModel与InterleavingModel：位于 src/minisweagent/models/extra/roulette.py，前者为每次查询随机选择配置好的多个模型之一，后者在多个模型间交替调用，常用于模型对比实验。对应导入路径为minisweagent.models.extra.roulette.RouletteModel与minisweagent.models.extra.roulette.InterleavingModel。详见 extra 模型参考文档。

此外，model_class字段支持任意可导入的 Python 路径——即使该自定义模型类尚未成为mini-swe-agent包的一部分，你也可以通过完整导入路径直接使用它，这为扩展自定义后端提供了极大的灵活性。

常见问题与排错要点

• 首次运行报“No default model set”：按提示运行mini-extra config setup，或设置MSWEA_MODEL_NAME环境变量。
• API Key 认证失败：litellm类模型在捕获到AuthenticationError时会在错误信息中提示用mini-extra config set KEY VALUE永久保存密钥；OpenRouter 后端的 401 响应也会给出同样的指引。
• 成本计算报错：如果模型未被litellm注册（例如免费或本地模型），可临时在配置中设置cost_tracking: "ignore_errors"，或全局导出MSWEA_COST_TRACKING="ignore_errors"（注意这会作用于所有模型），更稳妥的做法是为本地模型配置模型注册表LITELLM_MODEL_REGISTRY_PATH。
• 本地模型无法调用：检查是否已通过model_kwargs正确设置custom_llm_provider与api_base，并确认模型注册表中的litellm_provider与实际提供方一致（模型名大小写敏感）。

总结

mini-swe-agent的模型层设计遵循“默认可用、按需定制”的原则：一条mini-extra config setup即可完成默认模型与密钥配置；-m/--model、MSWEA_MODEL_NAME、YAML 配置三级机制灵活控制模型选择；model_kwargs支持透传 temperature、reasoning effort 等任意模型参数；而litellm、litellm_response、openrouter、portkey四类后端加deterministic、RouletteModel等实验类，覆盖了从云端主流模型、Responses API 到本地推理与模型对比实验的全部需求。结合本指南给出的源码级证据与可复制的配置示例，你可以快速为基准测试、日常开发或实验对比搭建合适的模型环境。

• 人工智能
• 大模型
• AI Agent
• 代码智能体