big-AGI 接入 OpenRouter多供应商模型统一配置指南【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGIbig-AGI 是一款开源的 AI 套件通过接入 OpenRouter 这一聚合 API 服务用户可以在同一份配置下使用 Anthropic、OpenAI、Google、DeepSeek、xAI 等众多供应商发布的数百个模型。本文以 docs/config-openrouter.md 为骨架结合仓库内 OpenRouter 供应商的完整实现厂商定义、服务配置 UI、模型列表处理与 OpenAI 兼容传输层系统讲解从账号注册、API Key 生成、界面配置到环境变量部署的完整流程并深入剖析密钥校验、免费模型限速、参数路由等底层机制帮助你在 big-AGI 中快速、安全、经济地启用 OpenRouter。一、OpenRouter 是什么为什么要用它OpenRouter 是一个独立的、付费的premiumAI 模型聚合服务它本身不训练模型而是通过一个统一 API转发来自多个提供商的模型请求。对 big-AGI 用户而言接入 OpenRouter 的最大价值在于一份 API Key、一个地址访问大量模型OpenRouter 的模型 ID 采用供应商/模型格式如anthropic/claude-*、openai/gpt-*、deepseek/deepseek-*big-AGI 会在界面上直接列出这些模型并支持选择使用模型可选择性高既有付费旗舰模型也提供一批免费模型见下文“免费模型限速”适合测试与低预算场景部署形态灵活既可以在 big-AGI 界面中按用户维度配置也可以通过环境变量在服务端启用适合 Docker、Kubernetes 等托管部署。从源码结构看OpenRouter 在 big-AGI 中并不是一个独立的协议实现而是作为OpenAI 兼容方言dialect接入的它复用 OpenAI 的 Chat Completions 传输层仅在请求头、参数映射和模型目录处理上做 OpenRouter 专属定制。这一点在 openai.access.ts 中明确列出该模块支持包括openrouter在内的 20 种 OpenAI 兼容方言。二、OpenRouter 账号注册与 API Key 生成在配置 big-AGI 之前需要先在 OpenRouter 侧完成账号与密钥准备共三步注册账号访问 openrouter.ai点击Sign In Continue with Google完成注册。充值余额进入 openrouter.ai/account点击Add Credits Pay with Stripe进行充值最低充值 5 美元。OpenRouter 按用量从余额中扣费余额不足会导致请求失败。生成 API Key进入 openrouter.ai/keys点击API Key Generate API Key生成密钥。关于密钥有两点务必注意立即复制并安全保存生成的密钥形如sk-or-v1-...关闭页面后不会再次显示严格保密持有该密钥即可消耗你的余额切勿提交到公共仓库或分享给他人。密钥格式提示big-AGI 在 openrouter.vendor.ts 中通过isValidOpenRouterKey函数校验密钥合法性——要求以sk-or-开头且长度大于 40 个字符。如果你的密钥不满足此格式界面会直接提示错误可对照检查是否复制完整。三、在 big-AGI 界面中集成 OpenRouter3.1 添加供应商并填写 API Key启动 big-AGI 后按以下步骤操作进入AI Models模型设置页面点击Add Vendor添加供应商在下拉列表中选择OpenRouter在弹出的OpenRouter API Key输入框中粘贴你的密钥点击Models刷新模型列表按钮加载可用的模型。模型列表加载完成后所有受支持供应商的模型都会出现在 big-AGI 的模型选择器中可直接用于聊天、Beam 多模型对话等场景。3.2 高级选项Require Parameters 与客户端直连在 OpenRouter 服务配置面板中big-AGI 还提供两个高级开关对应源码 OpenRouterServiceSetup.tsxRequire Parameters严格/默认开启后StrictOpenRouter 只把请求路由到支持你请求中全部参数如temperature、top_p、tools的提供商关闭时Default不支持的参数会被静默丢弃。如果你的应用依赖精确的参数控制建议开启如果更看重路由可用性则保持默认。客户端直连Client-Side Fetch开启后浏览器将直接连接 OpenRouter API而不是经由 big-AGI 服务端转发。该选项只有在已填写 API Key 时可用适合希望减少服务端中继的场景。3.3 更便捷的 OAuth 免填 Key除了手动粘贴密钥big-AGI 还内置了 OpenRouter 的OAuth 登录能力点击配置面板中的Link OpenRouter Key / Create New Key按钮应用会跳转到openrouter.ai/auth?callback_url...完成授权并自动回填密钥回调逻辑见 OpenRouterServiceSetup.tsx仓库中 openrouter.oauth.ts 保留了基于 PKCE 的完整参考实现。配置完成后面板中的check usage链接可直接跳转 OpenRouter 查看用量。四、通过环境变量启用 OpenRouter服务端配置除了在界面中按用户配置big-AGI 还支持服务端统一配置只要在启动时设置环境变量即可为所有用户启用 OpenRouter无需每个用户各自填写密钥。具体说明见 environment-variables.md。4.1 变量清单变量说明必填性OPENROUTER_API_KEYOpenRouter 的 API Key可选设置后服务端即启用该供应商在 environment-variables.md 中OPENROUTER_API_KEY被归类为 Backend Variables——即只在服务端代码运行时使用对应的官方说明是“以下变量被设置后会在服务端启用对应的 LLM无需用户再输入 API Key”。4.2 本地开发与 Docker 部署本地开发 / 云部署在启动 Next.js 服务前定义该变量Docker通过--env-file或-e传入容器Kubernetes变量已预置在 Secret 模板 env-secret.yaml 中OPENROUTER_API_KEY: 替换为实际密钥后注入 Deployment 即可。示例本地 shellexport OPENROUTER_API_KEYsk-or-v1-...需要说明环境变量配置与界面配置是两种互补方式。界面配置按用户保存在浏览器端环境变量则在服务端全局生效且优先级更高适合团队统一管控的部署场景。五、源码视角OpenRouter 供应商在 big-AGI 中的实现5.1 供应商定义与密钥校验OpenRouter 供应商的核心定义位于 openrouter.vendor.ts默认 API 地址https://openrouter.ai/api见 openai.access.ts 中的DEFAULT_OPENROUTER_HOST展示属性displayGroup: popular、instanceLimit: 1、hasFreeModels: true并声明了服务端配置键hasLlmOpenRouter即上面提到的环境变量开关传输方式rpcUpdateModelsOrThrow直接复用 OpenAI 供应商的模型刷新实现dialect: openrouter证明其走的是 OpenAI 兼容协议。5.2 免费模型的节流限速由于 OpenRouter 的免费模型调用存在延迟big-AGI 在rateLimitChatGenerate中实现了请求节流openrouter.vendor.ts对免费模型两次生成请求之间强制等待5 秒 100ms 安全余量对付费模型间隔仅 100ms。这意味着在使用 OpenRouter 免费模型时快速连续发送多轮消息会被自动排队限速这是上游服务的固有约束并非故障。5.3 模型目录的清洗与排序OpenRouter 的模型列表 API 是公开的测试代码 listModels.test.ts 注释明确指出“listing is PUBLIC, any bearer accepted”。big-AGI 在 openrouter.models.ts 中对其做了两层处理家族排序按anthropic/、deepseek/、google/、openai/、x-ai/、meta/等前缀定义展示优先级把常用旗舰厂商排在前面可见性过滤模型家族前缀不在允许列表中的默认隐藏hidden并剔除openai/gpt-3.5-turbo、meta-llama/llama-3-、openai/gpt-4等老旧或易混淆的模型 ID避免历史模型污染选择器。此外模型的~vendor/model路由别名会被自动去~前缀以匹配所属家族_orUnalias函数确保排序与分组正确。5.4 请求传输层的 OpenRouter 适配在真正的请求发送层openai.chatCompletions.tsbig-AGI 针对openrouter方言做了多项适配Sticky Session ID由客户端生成session_id发送给 OpenRouterOpenRouter 自身不签发用于保持提供商路由粘性、延续 prompt 缓存统一推理参数OpenRouter 方言下AnthropicClaude 4.x/6.x的 effort/thinking、Gemini 的预算级推理、OpenAI 兼容模型的 effort 都会被映射为 OpenRouter 的统一reasoning参数图像输出扩展通过 OpenAI ChatCompletions 协议传递图像生成配置如宽高比、尺寸Web 搜索/抓取工具对支持工具Function接口的模型以openrouter:web_search、openrouter:web_fetch服务端工具形式下发由 OpenRouter 代为执行检索循环引擎包括auto、native、exa、parallel、perplexity、firecrawl等见 aix.wiretypes.openrouter.ts 与 openrouter.webtools.ts。这些适配使得你在 big-AGI 中通过 OpenRouter 使用不同厂商的模型时推理参数、工具调用、图像输出等能力都能获得接近原生接入的体验。六、定价与费用提示OpenRouter 独立运营其服务与定价与 big-AGI 无任何从属关系。以下几点务必留意计费独立所有扣费均由 OpenRouter 收取模型单价以其官方模型页openrouter.ai/docs#models公示为准大模型成本高运行参数规模较大的模型如 GPT-4 系列、Claude 旗舰版本费用可观可能快速消耗余额用前查价使用前请在 OpenRouter 官网核对目标模型的定价每百万 token 输入/输出价格并根据场景合理选择免费模型或性价比模型。big-AGI 在服务配置面板中也内置了ApproximateCosts近似费用展示组件见 OpenRouterServiceSetup.tsx可辅助估算所选模型的成本。七、常见问题速查问题排查方向密钥粘贴后报错检查是否以sk-or-开头且完整长度 40重新复制生成页面中的密钥模型列表为空确认账号已充值最低 $5、密钥有效然后点击 Models 重新拉取免费模型请求很慢/被排队属正常限速big-AGI 会为免费模型自动增加 5 秒间隔某些模型在列表中不可见big-AGI 对老旧/小众家族模型做了默认隐藏属于设计行为需要团队统一接入改用服务端环境变量OPENROUTER_API_KEY配置而非逐用户填写结语OpenRouter 以“一个 API 接入多家模型”的模式让 big-AGI 的模型选择面大幅扩展而 big-AGI 通过将 OpenRouter 作为 OpenAI 兼容方言接入不仅提供了界面配置、OAuth 授权、服务端环境变量三种启用方式还在密钥校验、免费模型限速、模型目录清洗、推理参数统一映射等环节做了精细适配。结合本文的界面步骤与 config-openrouter.md、environment-variables.md 等文档以及 openrouter.vendor.ts、OpenRouterServiceSetup.tsx 等源码你可以快速完成从注册、配置到生产部署的完整接入。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考