第 3 章 · 01 LLM provider 配置

文档摘要

第 3 章 · 01 LLM provider 配置本节摘要:Strix 的能力上限由它接的模型决定——模型越强,代理越能规划、用工具、自我纠错。Strix 用 LiteLLM 做模型路由,统一支持 9 类 provider:OpenAI、Anthropic、OpenRouter、Google Vertex、AWS Bedrock、Azure、Novita 等 OpenAI 兼容云,以及完全离线的本地模型。本节先讲清 LiteLLM 的「路由原理 + 两个核心环境变量」,再用一张差异表对齐 9 类 provider 的配置要点,最后专门说明本地模型在「隐私 vs 性能」上的权衡与推荐选型,帮你为不同场景(云端最强模型 / 内网合规 / 离线气隙)选对模型。

第 3 章 · 01 LLM provider 配置

本节摘要:Strix 的能力上限由它接的模型决定——模型越强,代理越能规划、用工具、自我纠错。Strix 用 LiteLLM 做模型路由,统一支持 9 类 provider:OpenAI、Anthropic、OpenRouter、Google Vertex、AWS Bedrock、Azure、Novita 等 OpenAI 兼容云,以及完全离线的本地模型。本节先讲清 LiteLLM 的「provider/model-name 路由原理 + 两个核心环境变量」,再用一张差异表对齐 9 类 provider 的配置要点,最后专门说明本地模型在「隐私 vs 性能」上的权衡与推荐选型,帮你为不同场景(云端最强模型 / 内网合规 / 离线气隙)选对模型。

内容来源:原项目文档 docs/llm-providers/*.mdx(overview + openai + anthropic + openrouter + vertex + bedrock + azure + novita + local 共 9 篇),汉化并合并。

⚠️ 仅限授权测试:无论接哪个模型,Strix 仅用于测试你自己的应用或有书面授权的目标。

学习目标

阅读完本节,你应当能够:

说清 LiteLLM 的路由原理与 provider/model-name 模型格式。
用 STRIX_LLM 与 LLM_API_KEY 两个核心环境变量接上任意 provider。
用一张差异表对齐 9 类 provider 的认证方式与额外变量。
区分 API Key 类 provider 与 凭证类 provider(Vertex/Bedrock)的配置差异。
判断本地模型何时可用、何时该退回云端模型。
为「云端最强 / 内网合规 / 离线气隙」三类场景选对模型方案。

一、LiteLLM 路由:一个统一入口,9 类 provider

Strix 不为每家模型厂商写一套客户端,而是把所有模型请求交给 LiteLLM。LiteLLM 是一个统一网关:对上提供一致的 OpenAI 风格调用接口,对下翻译成各家 provider 的私有协议。这样 Strix 只需写一次模型调用代码,就能支持 100+ 个 LLM provider。

统一的代价是一个模型格式约定——你必须用 provider/model-name 的形式告诉 LiteLLM 走哪条路:


openai/gpt-5.4
anthropic/claude-sonnet-4-6
vertex_ai/gemini-3-pro-preview
bedrock/anthropic.claude-4-5-sonnet-20251022-v1:0
ollama/llama4

斜杠前是 provider 路由键(如 openai、anthropic、vertex_ai、bedrock、ollama),斜杠后是该 provider 下的模型名。改模型只需改这个字符串,Strix 的其余配置不变。

💡 一句话:Strix 的模型配置 = LiteLLM 路由键(STRIX_LLM)+ 认证凭证(LLM_API_KEY 或云厂商凭证)。两者到位,模型就通。

二、两个核心环境变量

无论接哪个 provider,这两个变量是通用的:

变量	作用	示例
`STRIX_LLM`	模型路由键,决定走哪个 provider、哪个模型	`openai/gpt-5.4`
`LLM_API_KEY`	API 密钥(对 OpenAI/Anthropic/OpenRouter 等大多数 provider)	`sk-...`

最小化配置只有两行:


export STRIX_LLM="openai/gpt-5.4"
export LLM_API_KEY="your-api-key"

对云厂商原生凭证的 provider(Vertex、Bedrock),不需要 LLM_API_KEY,改用各自 SDK 的认证机制(见下一节差异表)。

⚠️ OpenAI 兼容 API 的关键变量:LLM_API_BASE。很多第三方推理服务(Novita、自建网关、OpenAI 兼容代理)用 openai/ 路由键,但服务地址不同——这时用 LLM_API_BASE 覆盖默认的 https://api.openai.com。这是「接入任意 OpenAI 兼容服务」的万能开关。

三、9 类 provider 配置差异表

下表把 9 类 provider 的核心配置差异对齐。认证分两类:API Key 类(一个密钥搞定)与云凭证类(走云厂商 SDK 的 IAM / 服务账号)。

Provider	路由键	认证方式	代表模型	额外变量 / 备注
OpenAI	`openai/`	API Key	`openai/gpt-5.4`	兼容 API 用 `LLM_API_BASE` 覆盖
Anthropic	`anthropic/`	API Key	`anthropic/claude-sonnet-4-6`	密钥前缀 `sk-ant-`
OpenRouter	`openrouter/`	API Key	`openrouter/openai/gpt-5.4`	格式 `openrouter/<provider>/<model>`,一个密钥接 100+ 模型,自带故障转移与成本统计
Novita(OpenAI 兼容)	`openai/`	API Key	`openai/moonshotai/kimi-k2.5`	必须 `LLM_API_BASE=https://api.novita.ai/openai`;性价比高、上下文大、支持函数调用
Google Vertex AI	`vertex_ai/`	云凭证(Google ADC)	`vertex_ai/gemini-3-pro-preview`	需 `pipx install "strix-agent[vertex]"`;设 `VERTEXAI_PROJECT` / `VERTEXAI_LOCATION`;无 API Key
AWS Bedrock	`bedrock/`	云凭证(AWS)	`bedrock/anthropic.claude-4-5-sonnet-20251022-v1:0`	需 `pipx install "strix-agent[bedrock]"`;设 `AWS_PROFILE` / `AWS_REGION` 或 AK/SK;需 `bedrock:InvokeModel` 权限
Azure OpenAI	`azure/`	API Key + 终端	`azure/<deployment-name>`	需 `AZURE_API_KEY` / `AZURE_API_BASE` / `AZURE_API_VERSION`;路由键后是部署名而非模型名
本地 Ollama	`ollama/`	无(本地)	`ollama/qwen3-vl`	设 `LLM_API_BASE=http://localhost:11434`
本地 LM Studio / vLLM	`openai/`	无(本地)	`openai/local-model`	设 `LLM_API_BASE=http://localhost:1234/v1`(端口随运行器变)

3.1 API Key 类:三行配置

OpenAI、Anthropic、OpenRouter、Novita 这类 provider 配置最简单,设两个变量即可:


# OpenAI
export STRIX_LLM="openai/gpt-5.4"
export LLM_API_KEY="sk-..."

# Anthropic
export STRIX_LLM="anthropic/claude-sonnet-4-6"
export LLM_API_KEY="sk-ant-..."

# OpenRouter(一个密钥接 100+ 模型)
export STRIX_LLM="openrouter/openai/gpt-5.4"
export LLM_API_KEY="sk-or-..."

# Novita(OpenAI 兼容,必须覆盖 base)
export STRIX_LLM="openai/moonshotai/kimi-k2.5"
export LLM_API_KEY="your-novita-api-key"
export LLM_API_BASE="https://api.novita.ai/openai"

获取密钥的位置:OpenAI 在 platform.openai.com → API Keys;Anthropic 在 console.anthropic.com → API Keys;OpenRouter 在 openrouter.ai → Keys;Novita 在 novita.ai 仪表盘 → API Keys。

💡 OpenRouter 的价值:它是「模型超市」——一个 API Key 就能切换 OpenAI / Anthropic / Google / Meta 等各家模型,还自带 provider 间故障转移(failover)与跨模型成本统计。想在多个模型间快速 A/B 对比时,换 STRIX_LLM 字符串即可,密钥不动。

3.2 云凭证类:Vertex 与 Bedrock

Vertex 和 Bedrock 不用 API Key,而是走各自云厂商 SDK 的认证。好处是和企业现有 IAM 体系打通,坏处是前置准备更重。

Google Vertex AI(Gemini 3 系列):


# 安装 vertex 扩展
pipx install "strix-agent[vertex]"

# 配置(无 API Key,用应用默认凭证 ADC)
export STRIX_LLM="vertex_ai/gemini-3-pro-preview"
export VERTEXAI_PROJECT="your-project-id"
export VERTEXAI_LOCATION="global"

# 认证二选一:gcloud CLI 或服务账号
gcloud auth application-default login
# 或
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

前置:在 Google Cloud 项目里启用 Vertex AI API,确保账号有 Vertex AI User 角色。

AWS Bedrock(Claude 4.5 / Titan 系列):


# 安装 bedrock 扩展
pipx install "strix-agent[bedrock]"

# 配置(无 API Key,用 AWS 凭证)
export STRIX_LLM="bedrock/anthropic.claude-4-5-sonnet-20251022-v1:0"

# 认证三选一
export AWS_PROFILE="your-profile"      # 方式1:CLI Profile
export AWS_REGION="us-east-1"
# 或
export AWS_ACCESS_KEY_ID="AKIA..."     # 方式2:AK/SK
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# 方式3:EC2/ECS 实例角色(自动)

前置:在 Bedrock 控制台开启模型访问权限,确保 IAM 角色/用户有 bedrock:InvokeModel 权限。

3.3 Azure:介于两者之间

Azure OpenAI 既要 API Key,又要终端地址和 API 版本,且路由键后跟的是部署名(你在 Azure 门户里给模型起的名字),而非模型名:


export STRIX_LLM="azure/gpt-5.4-deployment"     # 部署名,非模型名
export AZURE_API_KEY="abc123..."
export AZURE_API_BASE="https://mycompany.openai.azure.com"
export AZURE_API_VERSION="2025-11-01-preview"

前置:创建 Azure OpenAI 资源 → 部署模型 → 从门户拿到终端 URL 与 API Key。

⚠️ Azure 易错点:STRIX_LLM 里的 azure/ 后面是你的部署名,不是模型名。部署名是你创建部署时自定义的,与模型名可以完全不同。模型名在部署时选好,之后就不用管了。

四、本地模型:隐私优先,但能力打折

本地模型让 Strix 完全离线运行,数据不出本机——这对敏感内网、气隙环境、合规要求严苛的场景至关重要。但这是一笔明确的「隐私换性能」交易。

4.1 隐私 vs 性能对照

维度	本地模型	云端模型(GPT-5 / Claude 4.5)
隐私	数据留在本机	数据发送给 provider
成本	免费(仅硬件)	按 token 付费
推理能力	较弱(代理任务吃力)	业界最强
部署	复杂(需 GPU)	即开即用

⚠️ 兼容性警告:Strix 严重依赖模型的 agentic 能力——工具调用、多步规划、自我纠错。大多数本地模型,尤其是 70B 参数以下的,在这些复杂任务上表现挣扎。对关键评估,强烈建议用 Claude 4.5 Sonnet 或 GPT-5 这类云端最强模型。只有当隐私是绝对第一优先级时,才用本地模型。

4.2 Ollama:最简单的本地方案

Ollama 是在 macOS/Linux/Windows 上跑本地模型最省事的方案:


# 1. 安装 Ollama(从 ollama.ai)
# 2. 拉一个高性能模型
ollama pull qwen3-vl

# 3. 配置 Strix
export STRIX_LLM="ollama/qwen3-vl"
export LLM_API_BASE="http://localhost:11434"

推荐模型(推理与工具调用的最佳平衡):

Qwen3 VL:ollama pull qwen3-vl
DeepSeek V3.1:ollama pull deepseek-v3.1
Devstral 2:ollama pull devstral-2

4.3 LM Studio / vLLM / 其他 OpenAI 兼容运行器

如果你用 LM Studio、vLLM 或其他本地推理服务,它们都暴露 OpenAI 兼容接口,用 openai/ 路由键 + LLM_API_BASE 接入:


export STRIX_LLM="openai/local-model"
export LLM_API_BASE="http://localhost:1234/v1"   # 端口随运行器变

💡 选型建议:纯离线/气隙 → Ollama + Qwen3 VL;内网合规但允许私有云 → 走 Bedrock/Vertex(数据仍在你的 AWS/GCP 账号内,但用最强模型);一般情况 → 直接用 OpenAI 或 Anthropic 最强模型,别在能力上让步。

五、配置验证与排错

配完环境变量后,用一个最小目标快速验证模型链路是否通:


# 设好 STRIX_LLM 与凭证后,跑一次最小扫描
strix --target https://example.com --scan-mode quick --max-budget 5

常见问题:

认证失败(401/403):API Key 写错、过期,或云凭证未配置(Vertex 检查 gcloud auth,Bedrock 检查 AWS_PROFILE 与权限)。
OpenAI 兼容服务报「模型不存在」:忘了设 LLM_API_BASE,或 base 地址末尾路径不对(Novita 要带 /openai,LM Studio 要带 /v1)。
Vertex/Bedrock 安装报错:忘了装扩展(pipx install "strix-agent[vertex]" / [bedrock])。
本地模型「不调工具」「乱规划」:这不是配置问题,而是模型能力不足——退回云端最强模型,或换推荐的本地大模型(70B+)。
Azure 报「部署不存在」:STRIX_LLM 里写成了模型名,应改成你在门户里创建的部署名。

本节要点回顾

路由原理:Strix 用 LiteLLM 做统一模型网关,模型格式为 provider/model-name,改模型只改这个字符串。
两个核心变量:STRIX_LLM(路由键)与 LLM_API_KEY(API Key 类 provider 的密钥);OpenAI 兼容服务额外用 LLM_API_BASE 覆盖服务地址。
API Key 类 provider:OpenAI / Anthropic / OpenRouter / Novita——三行配置即可,其中 OpenRouter 一个密钥接 100+ 模型并自带故障转移。
云凭证类 provider:Vertex(需 vertex 扩展 + Google ADC + 项目/位置)、Bedrock(需 bedrock 扩展 + AWS 凭证 + InvokeModel 权限)——不用 API Key,走各自 SDK 认证。
Azure 介于两者之间:既要 API Key 又要终端地址和 API 版本,且 STRIX_LLM 后是部署名而非模型名。
本地模型=隐私换性能:完全离线,但 70B 以下模型在 agentic 任务上吃力;关键评估用云端最强模型,只在隐私绝对优先时用本地,推荐 Qwen3 VL / DeepSeek V3.1 / Devstral 2。
场景选型:云端最强 → OpenAI/Anthropic;内网合规 → Bedrock/Vertex(数据留在自己云账号);离线气隙 → Ollama 本地大模型。

下一节,我们看 Strix 如何用 root agent 把这些模型调度成一组协作的专家代理——模型决定能力上限,多代理编排决定能不能逼近这个上限。