> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent-mintlify-f21cea86.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 多提供商故障切换的 LLM 编排

> Arka 如何编排 24 家 LLM 提供商，实现自动故障切换、API 密钥轮换、按任务的配置文件以及按技能的模型覆盖。

Arka 的 `LlmFallbackEngine` 管理跨 **25 家提供商**的所有 LLM 调用，支持自动故障切换、API 密钥轮换以及按任务或按技能的模型覆盖。

## 支持的提供商

Anthropic、OpenAI、Gemini、Groq、xAI、DeepSeek、Moonshot、Z.AI、MiniMax、Venice、Mistral、Cohere、Together、Fireworks、Perplexity、Hugging Face、OpenRouter、Sakana Fugu、Bedrock、Azure、LiteLLM、Ollama、LM Studio、vLLM 以及 vLLM Cloud。

## 故障切换的工作方式

编排器按以下顺序构建候选列表：

1. `AI_PREFERRED_PROVIDER` + `AI_PREFERRED_MODEL`（若已设置）
2. 从各提供商 API 获取的实时模型列表（当密钥允许时）
3. 内置链：Gemini 2.5/2.0 Flash → Groq Llama 3.3/3.1 → Ollama cloud/local

遇到 429、401 或超时时，Arka 会尝试下一个模型。API 密钥轮换（`API_KEY_ROTATION=1`）会在切换提供商前先循环使用备份密钥。

```env theme={null}
AI_PREFERRED_PROVIDER=gemini
AI_PREFERRED_MODEL=gemini-2.0-flash
LLM_AUTO_FALLBACK=1
API_KEY_ROTATION=1
```

当你使用 `arka provider set groq`（或在 fish 中使用 `ai-pref groq`）切换提供商时，Arka 会先尝试在新提供商上**保留相同的模型**，然后才回退到该提供商的默认模型。要禁用此行为，请使用 `arka provider set groq --no-keep-model` 或 `AI_KEEP_MODEL_ON_PROVIDER_SWITCH=0`。

## Web 聊天模型顺序

交互式 Web 聊天（例如 [Open WebUI 前端](/cn/guides/open-webui)）使用单独的快速链，这样即使云端免费额度触发速率限制，回复也能持续返回：

1. 当 Ollama 正在运行时，使用一个小型本地 Ollama 模型。Arka 会从 `llama3.2:1b`、`llama3.2:3b`、`qwen3:8b` 和 `llama3.1:8b` 中选择第一个已安装的模型。
2. 当设置了 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` 时，使用 Gemini Flash 模型。
3. 当设置了 `GROQ_API_KEY` 时，使用 Groq `llama-3.3-70b-versatile`。

覆盖该链或本地模型：

```env theme={null}
WEB_CHAT_OLLAMA_MODEL=llama3.2:3b
WEB_CHAT_MODEL_CHAIN=ollama/qwen3:8b,groq/llama-3.3-70b-versatile
```

设置 `WEB_CHAT_FAST=0` 可改用标准故障切换链。

<Note>
  对于 "thanks" 或 "got it" 这类简短的确认语，Arka 会回复一句简短的欢迎语，不会继续之前的构建。
</Note>

## 按任务的配置文件

| 任务 | 用途 |
| - | - |
| `route` | 技能路由决策 |
| `summarize` | 邮件和文档摘要 |
| `chat` | 对话式回复 |
| `research` | 深度网络研究 |
| `agent` | 目标代理的步骤 |
| `pdf` | PDF 问答 |
| `arka predictions` | 股票和预测分析 |
| `compose_video` | 视频脚本生成 |
| `arka compose_slides` | 演示幻灯片脚本生成 |

按任务覆盖：

```env theme={null}
LLM_FALLBACK_ROUTE=gemini/gemini-2.0-flash,groq/llama-3.3-70b-versatile
LLM_FALLBACK_SUMMARIZE=groq/llama-3.3-70b-versatile
```

## 按技能模型

```bash theme={null}
arka ai-skill-model web_answer groq/llama-3.3-70b-versatile
arka ai-skill-model profiles
arka ai-models
```

或编辑 `~/.config/arka/llm-skill-models.json`。

## 基准测试编排

如果你希望模型选择跟随实时基准测试的优胜者，请先运行基准测试套件，然后启用编排：

```bash theme={null}
arka benchmark run
arka benchmark show
ARKA_BENCHMARK_ORCHESTRATE=1 arka orchestrate --benchmark "how to get free ai credits"
```

基准测试配置文件跟随路由后的任务。路由到 `web_answer` 的请求使用 `chat` 基准测试结果。代理类请求使用 `agent`。

## 共享的耗尽缓存

Arka 维护一个会话缓存。在你重置缓存之前，它会在所有技能中跳过已耗尽的模型：

```bash theme={null}
arka ai reset-exhaustion
```

在故障切换时启用 stderr 通知：`LLM_FALLBACK_NOTIFY=1`。调试尝试过程：`LLM_VERBOSE=1`。

## 本地 LLM 服务器

```env theme={null}
OLLAMA_HOST=127.0.0.1:11434
LLM_AUTO_START_SERVERS=1
LLM_AUTO_STOP_SERVERS=1
```

## 为什么技能保持简洁

Arka **不会**让 LLM 去记忆 70 个技能手册。技能是本地程序。模型只需选出正确的名称。在 LLM 路由时，Arka 会传递：

* 一份**紧凑的技能目录**（仅包含已注册的名称）
* **精选路由规则**（高信噪比的模式）
* 通过 `ROUTE_ALIASES` 传入的**你机器上的 shell 别名**

路由任务使用低 temperature 和专用链，让快速、低成本的模型处理分类。重型工作在本地技能内部执行。

## 运行时检查

```bash theme={null}
arka ai-models
arka ai models --task summarize
arka ai models --skill web_answer
arka ai active-model
arka ai reset-exhaustion
```

<Note>
  设置 `SHOW_MODEL=1`（默认值）可在答案下方显示 `Model: provider/name`。
</Note>

## 相关内容

<CardGroup cols={2}>
  <Card title="配置" icon="settings" href="/cn/reference/configuration">环境变量与 API 密钥</Card>
  <Card title="对话与网络" icon="message-circle" href="/cn/guides/chat">使用编排器的技能</Card>
  <Card title="故障排查" icon="wrench" href="/cn/reference/troubleshooting">401、429 与故障切换修复</Card>
</CardGroup>


## Related topics

- [符号与 LLM 路由管道](/cn/concepts/routing.md)
- [硬件感知的模型选择](/cn/guides/select-model.md)
- [Sakana Fugu 编排器](/cn/guides/fugu.md)
- [Arka 与其他智能体的对比](/cn/concepts/comparison.md)
- [Arka 简介](/cn/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.