add-model-provider

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add a Model Provider

添加模型提供商

Deliver a provider that users can configure, recognize, and use through the supported API paths. This skill includes the provider documentation workflow.

Paths below are relative to the open-source repository root. In a Cloud checkout, prefix them with

lobehub/

and follow the parent repository's install and Git rules. Hosted model configuration is a separate workflow: use the deployment operator's model-onboarding process when that is the requested target. Do not copy private deployment settings or routing information into this skill or an OSS change.

For a documentation-only request, inspect the implemented configuration and follow Provider documentation; do not add runtime code merely to satisfy this checklist.

For a model-only request on an existing provider, follow model-bank-metadata for

knowledgeCutoff

family

, and

generation

, using its single-model guidance rather than the repo-wide sweep. Use the research and focused validation below for other model-card fields, including capabilities, pricing, and context limits. Skip new provider registration, authentication configuration, and provider-list reordering unless the requested model exposes a confirmed gap in those paths.

交付一个用户可通过支持的API路径进行配置、识别和使用的提供商。本技能包含提供商文档工作流。

以下路径均相对于开源仓库根目录。在Cloud检出中，需为其添加

lobehub/

前缀，并遵循父仓库的安装与Git规则。托管模型配置是独立的工作流：若请求目标为托管模型，请使用部署运营商的模型接入流程。请勿将私有部署设置或路由信息复制到本技能或OSS变更中。

对于仅涉及文档的请求，请检查已实现的配置并遵循提供商文档；请勿仅为满足本检查清单而添加运行时代码。

对于现有提供商的仅新增模型请求，请遵循模型库元数据中关于

knowledgeCutoff

、

family

和

generation

的说明，使用其单模型指导而非仓库级别的全量扫描。对于其他模型卡片字段（包括功能、定价和上下文限制），请使用下文的调研和针对性验证方法。除非请求的模型明确暴露了这些路径中的缺口，否则跳过新提供商注册、身份验证配置和提供商列表重排序。

Establish the Integration Contract

确立集成契约

Distinguish a new provider from a model added to an existing provider. Record the stable provider ID, display name, model IDs, authentication method, endpoint, and supported API modes. File/export casing may differ from the lowercase provider ID; follow actual consumers.
Read the official announcement, API reference, model catalog, pricing, and migration notes. Record source URLs and access dates for capabilities, constraints, and pricing. Search for announcements as well as documentation: parameter changes often appear only in release notes. Use a rendered browser when a fetched page is an empty client-rendered shell.
Verify the endpoint actually being integrated. A model's advertised capabilities do not prove that a compatible endpoint supports its search parameters, tools, images, or structured output. Do not describe a third-party endpoint or its credentials as the provider's official API.
For local servers or desktop applications, read Local provider integration. Verify launch modes, installed-model discovery, browser access, and capability refresh separately; an OpenAI-compatible model list alone does not establish these behaviors.
Compare the latest provider addition and the closest existing implementation by protocol and authentication. Read their diffs, not just file lists. Integration map and precedents identifies the registration chain and contrasting examples; historical omissions are not requirements to repeat.
Set model metadata from evidence: exact IDs, family/generation, context and output limits, release/cutoff dates when known, capabilities, extend parameters, search behavior, pricing currency and units. Distinguish API usage prices from subscription entitlements, cached input from ordinary input, and current promotions from list prices. Mark unknowns rather than inventing values; preserve existing supported models.

区分新增提供商与向现有提供商添加模型的场景。记录稳定的提供商ID、显示名称、模型ID、身份验证方法、端点和支持的API模式。文件/导出的大小写可能与小写的提供商ID不同；请遵循实际使用方的规范。
阅读官方公告、API参考、模型目录、定价和迁移说明。记录功能、限制和定价的来源URL及访问日期。既要搜索文档也要搜索公告：参数变更通常仅出现在发布说明中。当获取的页面是空白的客户端渲染壳时，请使用渲染后的浏览器（获取内容）。
验证实际要集成的端点。模型宣传的功能不能证明兼容端点支持其搜索参数、工具、图像或结构化输出。请勿将第三方端点或其凭证描述为提供商的官方API。
对于本地服务器或桌面应用，请阅读本地提供商集成。分别验证启动模式、已安装模型发现、浏览器访问和功能刷新；仅靠OpenAI兼容的模型列表不足以支撑这些行为。
按协议和身份验证方式，将最新添加的提供商与最接近的现有实现进行对比。阅读其差异内容，而不仅仅是文件列表。集成图谱与先例明确了注册链和对比示例；历史遗漏不代表需要重复（这些遗漏）。
基于证据设置模型元数据：准确的ID、系列/代际、上下文和输出限制、已知的发布/截止日期、功能、扩展参数、搜索行为、定价货币和单位。区分API使用价格与订阅权益、缓存输入与普通输入、当前促销与标价。标记未知项而非编造值；保留现有支持的模型。

Implement the Provider

实现提供商

Use Integration map and precedents while tracing the request from settings through configuration to the runtime.

Register the provider ID, provider card, separate model cards, model imports/map/exports, and package subpath export. Keep
```
chatModels: []
```
on modern provider cards when the separate model bank is the source of truth.
Set a usable static
```
checkModel
```
when the provider guarantees that model is available. Otherwise, omit it and let the user select and persist a connection-check model from the fetched local list; do not put an arbitrary example in the card. Set accurate authentication, model-fetching, SDK-family, and browser-request settings. A static model catalog may be correct when the API has no model-list endpoint. Trace consumers of both top-level and nested browser-request flags before relying on one of them.
Reuse the appropriate runtime factory or adapter. Register the runtime and its public export. If the provider needs a distinct routed API adapter, wire the RouterRuntime API type and base-runtime map too; provider registration alone does not establish that path.
Validate protocol selection separately for streaming chat, non-streaming chat, and structured generation. Responses-only providers may need both chat and
```
generateObject
```
configuration, plus protection against a caller selecting an unsupported mode. Map tools, search, response formats, and reasoning only where supported. Never enable a capability solely because a sibling provider does.
Add authentication/configuration plumbing appropriate to the provider. For API-key providers, check both environment schema and runtime bindings, then the generic server configuration and runtime initialization. OAuth providers need their authorization, refresh, disconnect, and account-metadata paths instead of invented API-key variables.
For a new user-facing parameter, trace the model-card type, stored chat configuration, controls, request resolver, and translations. Prefer existing parameter definitions when their semantics match. If reasoning state must survive multiple turns, test serialization and replay through the real stream/non-stream paths rather than only the initial request.

Keep changes to shared factories or error handlers conditional on an observed gap. The checklist is not a mandate to modify every listed file.

在跟踪请求从设置到配置再到运行时的流程时，请参考集成图谱与先例。

注册提供商ID、提供商卡片、独立模型卡片、模型导入/映射/导出，以及包子路径导出。当独立模型库是可信来源时，在现代提供商卡片中保持
```
chatModels: []
```
的设置。
当提供商保证模型可用时，设置一个可用的静态
```
checkModel
```
。否则省略该字段，让用户从获取的本地列表中选择并持久化连接检查模型；请勿在卡片中放置任意示例。设置准确的身份验证、模型获取、SDK系列和浏览器请求设置。当API没有模型列表端点时，静态模型目录可能是正确的。在依赖其中一个浏览器请求标志之前，请跟踪顶层和嵌套浏览器请求标志的所有使用方。
复用合适的运行时工厂或适配器。注册运行时及其公开导出。如果提供商需要独立的路由API适配器，还需连接RouterRuntime API类型和基础运行时映射；仅提供商注册不足以建立该路径。
分别验证流式聊天、非流式聊天和结构化生成的协议选择。仅支持响应的提供商可能同时需要聊天和
```
generateObject
```
配置，还需防止调用方选择不支持的模式。仅在支持的地方映射工具、搜索、响应格式和推理功能。绝不能仅因为同级提供商支持就启用某项功能。
添加适合该提供商的身份验证/配置管道。对于API密钥提供商，需同时检查环境模式和运行时绑定，然后检查通用服务器配置和运行时初始化。OAuth提供商需要其授权、刷新、断开连接和账户元数据路径，而非编造的API密钥变量。
对于新增的面向用户的参数，需跟踪模型卡片类型、存储的聊天配置、控件、请求解析器和翻译。当语义匹配时，优先使用现有参数定义。如果推理状态必须在多轮对话中保留，请通过真实的流式/非流式路径测试序列化和重放，而不仅仅测试初始请求。

对共享工厂或错误处理器的修改需以观察到的缺口为前提。本检查清单并非要求修改列出的每一个文件。

Branding, Ordering, and Documentation

品牌设计、排序与文档

Check provider and model icons independently in
```
@lobehub/icons
```
: the provider brand and model family can require different artwork. Inspect the actual model-ID matcher, including prefixes, case variants, and collisions with existing model names. When changing a matcher, verify the new IDs and preserve the older family's matches.
If an icon is missing, identify the missing asset/mapping and prepare an appropriate change or explicit fallback within the authorized scope. Do not silently use an unrelated brand. An external icon PR or release is a separate authorized action; verify that the consumer's installed release contains the intended mapping before claiming the UI is fixed.
Place the provider deliberately in
```
DEFAULT_MODEL_PROVIDER_LIST
```
; this array controls default list order, not imports or enum declarations. Apply these ordering principles:
- Favor providers with greater community popularity toward the front. Use current evidence of adoption and ecosystem recognition rather than alphabetical order, implementation convenience, or an invented numeric popularity score.
- Keep local model managers and inference servers together, such as Ollama, LM Studio, vLLM, and Unsloth Studio.
- Keep router/aggregator services together: services exposing models from multiple upstream providers through a unified API, such as OpenRouter and AIHubMix. Using the internal
```
RouterRuntime
```
  abstraction alone does not place a provider in this group.
- Group continuity takes precedence over strictly sorting every individual provider by popularity. Use community popularity to position groups and standalone providers, and to order providers within each group. Preserve an explicit user-specified position and existing user-customized ordering.
- Insert a new provider into its appropriate group without reordering unrelated providers. A requested broader ordering cleanup can move the affected peers together.
Follow Provider documentation for bilingual usage/setup instructions, environment references, existing Docker configuration, safe examples, and screenshots. Keep the public provider identity and actual credential/endpoint requirements consistent across UI and docs.
Add
```
<provider-id>.description
```
to
```
locales/en-US/providers.json
```
and
```
locales/zh-CN/providers.json
```
for the provider's description. The default namespace in
```
packages/locales/src/default/providers.ts
```
is derived from provider cards; do not duplicate the description there. Follow repository conventions for other new copy and verify fallback behavior. Avoid running a repository-wide translation job for a few provider keys.

在
```
@lobehub/icons
```
中独立检查提供商和模型的图标：提供商品牌和模型系列可能需要不同的设计素材。检查实际的模型ID匹配器，包括前缀、大小写变体，以及与现有模型名称的冲突。修改匹配器时，需验证新ID并保留旧系列的匹配规则。
如果缺少图标，请明确缺失的素材/映射，并在授权范围内准备合适的变更或明确的降级方案。请勿悄无声息地使用不相关的品牌。外部图标PR或发布是独立的授权操作；在声称UI已修复之前，请验证使用方安装的版本包含预期的映射。
将提供商合理放置在
```
DEFAULT_MODEL_PROVIDER_LIST
```
中；该数组控制默认列表顺序，而非导入或枚举声明。遵循以下排序原则：
- 社区知名度更高的提供商优先靠前。使用当前的采用率和生态认可度证据，而非字母顺序、实现便利性或编造的数字人气评分。
- 将本地模型管理器和推理服务器放在一起，例如Ollama、LM Studio、vLLM和Unsloth Studio。
- 将路由/聚合服务放在一起：通过统一API暴露多个上游提供商模型的服务，例如OpenRouter和AIHubMix。仅使用内部
```
RouterRuntime
```
  抽象并不足以将提供商归入此组。
- 分组连续性优先于按知名度严格排序每个单独的提供商。使用社区知名度来定位分组和独立提供商，并在每个分组内对提供商排序。保留用户明确指定的位置和现有用户自定义的排序。
- 将新提供商插入其合适的分组中，无需重新排序不相关的提供商。如果请求进行更广泛的排序清理，可将受影响的同类提供商一起移动。
遵循提供商文档编写双语使用/设置说明、环境参考、现有Docker配置、安全示例和截图。在UI和文档中保持公开的提供商身份和实际的凭证/端点要求一致。
向
```
locales/en-US/providers.json
```
和
```
locales/zh-CN/providers.json
```
中添加
```
<provider-id>.description
```
作为提供商的描述。
```
packages/locales/src/default/providers.ts
```
中的默认命名空间派生自提供商卡片；请勿在其中重复描述。其他新文案遵循仓库约定并验证降级行为。避免为少数提供商密钥运行全仓库范围的翻译任务。

Validate the User Path

验证用户路径

Use the existing provider test harness (

packages/model-runtime/src/providerTestUtils.ts

) and focused package tests. Cover the supported behavior rather than asserting that registration strings exist:

Provider/model lookup resolves the new cards and runtime; connection checking uses a supported model.
Requests select the intended API mode and endpoint, carry the right authentication, transform supported parameters, and preserve tool calls and structured results. Exercise streaming and non-streaming paths when supported.
Missing/invalid credentials, failed model fetching, and connection errors produce useful localized messages rather than raw codes or translation keys. Use synthetic HTTP responses for legacy/invalid wire payloads instead of casting them into a stricter current response type.
Trigger a connection failure and expand its details: the error must remain recoverable within the settings page. A successful connection does not exercise lazy error components or their shared UI contexts.
The provider settings page and model row display the intended name, icon, capabilities, and default order in light/dark themes. Check English and Chinese where copy changed. Inspect both provider and model icons in the real UI.
When shared runtime errors or lazy namespaces change, check other affected surfaces such as Workbench. Its separate language bundle may need a namespace even when the main application already loads it.

Run the owning repository's quality command and relevant package tests. For an OSS PR developed inside Cloud, verify the OSS type-check/build context as well: a passing parent type-check does not establish that the standalone OSS configuration passes. Attribute workspace-resolution failures separately; do not remove valid checks to manufacture a pass.

Use the repository's acceptance workflow for authorized live checks. Do not read secret files, put credentials into logs/screenshots, invent screenshots, or claim a successful inference from mocks. If live credentials or access are unavailable, report the precise unverified path and the completed offline checks.

When delivery includes a PR, follow repository commit/PR workflows and monitor CI and deployment for the current head. Attribute failures, fix in-scope issues, validate, push, and continue until checks complete or a concrete blocker is reached. Preserve applicable independent-review gates and human-only merge rules. Report changed behavior, validation, evidence, and remaining limitations.

使用现有的提供商测试工具（

packages/model-runtime/src/providerTestUtils.ts

）和针对性的包测试。覆盖支持的行为，而非仅断言注册字符串存在：

提供商/模型查找能解析新卡片和运行时；连接检查使用受支持的模型。
请求选择预期的API模式和端点，携带正确的身份验证信息，转换支持的参数，并保留工具调用和结构化结果。如果支持的话，需测试流式和非流式路径。
凭证缺失/无效、模型获取失败和连接错误会生成有用的本地化消息，而非原始代码或翻译键。对于旧版/无效的网络 payload，使用合成HTTP响应，而非将其强制转换为更严格的当前响应类型。
触发连接失败并展开其详情：错误必须在设置页面内可恢复。成功的连接不会测试懒加载错误组件或其共享的UI上下文。
提供商设置页面和模型行在浅色/深色主题下显示预期的名称、图标、功能和默认顺序。文案有变更的地方需检查英文和中文版本。在真实UI中检查提供商和模型的图标。
当共享运行时错误或懒加载命名空间变更时，检查其他受影响的界面，例如Workbench。即使主应用已经加载了语言包，其独立的语言包可能仍需要对应的命名空间。

运行所属仓库的质量检查命令和相关包测试。对于在Cloud中开发的OSS PR，还需验证OSS的类型检查/构建上下文：父仓库的类型检查通过不代表独立的OSS配置也能通过。单独归因工作区解析失败；请勿移除有效检查来制造通过的假象。

使用仓库的验收工作流进行授权的在线检查。请勿读取机密文件、将凭证放入日志/截图、编造截图，或声称基于mock的推理成功。如果无法获取在线凭证或访问权限，请报告确切的未验证路径和已完成的离线检查。

当交付内容包含PR时，遵循仓库的提交/PR工作流，并监控当前HEAD的CI和部署情况。归因失败、修复范围内的问题、验证、推送，持续进行直到检查完成或遇到具体的阻塞问题。保留适用的独立评审关卡和仅人工合并规则。报告变更的行为、验证结果、证据和剩余限制。