Tutorial / LLM Endpoints

LLM 端点与 API Key 配置

从 API Key 申请到多端点容灾，覆盖 `.env`、`llm_endpoints.json`、路由策略和上线验证。

配置模型访问层的正确顺序

OpenAkita 的模型访问层分为两层：`.env` 存密钥和全局参数，`llm_endpoints.json` 管理端点拓扑与策略。

先单端点跑通

先配置一个稳定端点验证基础链路，避免一次引入过多变量。

再增加备份端点

按优先级配置主备，明确每个端点的 `capabilities`。

最后做故障演练

主动模拟主端点失败，确认重试和回退策略按预期生效。

配图位：LLM 配置总览图建议放 `.env` 与 endpoints 文件关系图

配图位：模型调用链路图建议放请求 -> 路由 -> 端点 -> 回退流程图

上线建议：主端点优先选择稳定性高模型，备份端点优先选择区域近、成本低模型。

API Key 申请与管理

统一在平台控制台申请 API Key，按供应商将密钥写入环境变量，不要硬编码到仓库。

供应商	变量名	申请入口	建议
Anthropic	ANTHROPIC_API_KEY	console.anthropic.com	适合作为主端点
OpenAI	OPENAI_API_KEY	platform.openai.com	兼容生态广
DashScope	DASHSCOPE_API_KEY	dashscope.console.aliyun.com	国内网络友好
Kimi	KIMI_API_KEY	platform.moonshot.cn	中文场景常用
DeepSeek	DEEPSEEK_API_KEY	platform.deepseek.com	推理场景成本低
OpenRouter	OPENROUTER_API_KEY	openrouter.ai	多模型聚合
MiniMax	MINIMAX_API_KEY	platform.minimaxi.com	多模态补充
SiliconFlow	SILICONFLOW_API_KEY	cloud.siliconflow.cn	高并发性价比

配图位：控制台 Key 页面截图建议放申请入口和密钥生成流程

配图位：密钥管理规范图建议放轮换、禁用、审计策略示意图

每个环境（开发/测试/生产）使用独立 API Key。
为 Key 设置最小权限和配额上限，避免异常消耗。
密钥泄露后立即吊销并更新部署环境。

.env 配置模板

`.env` 负责统一声明 API Key、默认模型和网络参数。至少配置一个可用 Key。

# 复制模板
cp examples/.env.example .env

# 至少配置一个有效 API Key
ANTHROPIC_API_KEY=sk-xxx
DASHSCOPE_API_KEY=xxx
KIMI_API_KEY=xxx

# 端点配置文件
LLM_ENDPOINTS_CONFIG=data/llm_endpoints.json
DEFAULT_MODEL=claude-opus-4-5-20251101-thinking
MAX_TOKENS=8192

# 网络受限场景可配置
ALL_PROXY=http://127.0.0.1:7890

命名一致性

`api_key_env` 值必须和 `.env` 变量名完全一致，否则会出现 key not found。

配置隔离

不要把 `.env` 提交到 git。建议使用 `.env.production` 与部署系统密钥托管。

配图位：.env 编辑示例截图建议放关键变量高亮后的配置截图

`llm_endpoints.json` 多端点配置

推荐先通过向导生成，再按业务能力做精细化调整。

# 向导模式（推荐）
python -m openakita.llm.setup.cli

# 手动模板
cp data/llm_endpoints.json.example data/llm_endpoints.json

{
  "endpoints": [
    {
      "name": "claude-primary",
      "provider": "anthropic",
      "api_type": "anthropic",
      "base_url": "https://api.anthropic.com",
      "api_key_env": "ANTHROPIC_API_KEY",
      "model": "claude-opus-4-5-20251101-thinking",
      "priority": 1,
      "max_tokens": 8192,
      "timeout": 60,
      "capabilities": ["text", "vision", "tools", "thinking"]
    },
    {
      "name": "qwen-backup",
      "provider": "dashscope",
      "api_type": "openai",
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key_env": "DASHSCOPE_API_KEY",
      "model": "qwen3-max",
      "priority": 2,
      "timeout": 60,
      "capabilities": ["text", "tools", "thinking"],
      "extra_params": {
        "enable_thinking": true
      }
    }
  ],
  "settings": {
    "retry_count": 2,
    "retry_delay_seconds": 2,
    "health_check_interval": 60,
    "fallback_on_error": true
  }
}

配图位：端点编排示意图建议放主备端点优先级关系图

配图位：配置文件 diff 截图建议放模板与生产配置差异截图

能力路由与故障切换策略

通过 `capabilities` 和 `priority` 配置，把请求自动路由到最合适的模型端点。

能力	建议主端点	建议备份端点	说明
text	稳定高质量模型	低成本模型	覆盖绝大多数对话请求
tools	工具调用兼容性强模型	OpenAI 兼容模型	要求函数调用格式稳定
vision	多模态模型	支持图像输入的次级模型	需显式声明 `vision` 能力
thinking	推理强化模型	推理成本较低模型	建议设置较高超时时间

主端点 `priority` 设为 1，备份按 2、3 递增。
不同供应商的超时和重试策略分开评估，避免放大延迟。
出现持续失败时，检查端点状态与配额是否触发限流。

配图位：故障切换时序图建议放主端点失败后重试与回退流程

连通性验证与排障

完成配置后建议做三类验证：交互验证、任务验证、故障模拟验证。

# 交互验证
openakita

# 任务验证
openakita run "请总结当前 LLM 端点配置并输出检查项"

# 服务模式（如需 IM）
openakita serve

Q：报错 API key not found？

A：检查 `api_key_env` 与 `.env` 中变量名是否完全一致，并确认运行目录正确。

Q：报错 timeout 或 connection error？

A：优先检查 `base_url`、代理配置和供应商网络可达性，再调高 `timeout`。

Q：工具调用失败或参数错乱？

A：检查模型是否支持 tool-calling，必要时切换到兼容性更高端点。

视频教程与参考资料

替换为视频 1：API Key 申请与 `.env` 配置（B 站 / YouTube iframe）

替换为视频 2：多端点容灾策略实战（B 站 / YouTube iframe）

配图位：视频封面图 1建议放 API Key 配置封面

配图位：视频封面图 2建议放端点路由实战封面