在 AIRI 中接入 n1n：OpenAI 兼容聊天模型服务的配置指南-编程实验室

在 AIRI 中接入 n1n：OpenAI 兼容聊天模型服务的配置指南

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

n1n 是一家提供高性能 AI API 服务的云提供商，AIRI 以 OpenAI 兼容协议的方式将其接入"聊天"（chat）任务，让你在 n1n 账号上直接使用其模型服务。本文以 n1n 的接入文档为主线，结合 AIRI 仓库中provider-inference包的 n1n 服务商实现与校验器源码，完整讲解从准备服务访问、填写配置、执行验证到排障的每一步，读完即可在 AIRI 中完成 n1n 的配置与启用。

n1n 在 AIRI 中的定位

AIRI 通过"服务商"（Providers）机制统一管理各类模型推理服务。n1n 属于其中的云端服务商（在 stage-ui 的属性分类中被标记为paidCloud，即付费云端服务），其能力范围为tasks: ['chat']，也就是提供聊天补全（chat completions）能力。

从 n1n 服务商实现可以看到，其底层通过createOpenAI（来自@xsai-ext/providers/create）构造 OpenAI 兼容客户端，这意味着 n1n 暴露的是标准的 OpenAI 风格 API。因此，AIRI 中任何按 OpenAI 兼容协议编写的校验逻辑与调用链路都可以直接复用于 n1n。

核心配置项一览

n1n 服务商的配置结构（对应源码中的n1nConfigSchema，见 index.ts）只有两个字段：

配置项	是否必填	默认值	说明
`apiKey`	可选	无	n1n 服务账号的 API Key，部署允许匿名访问时可留空
`baseUrl`	可选	`https://api.n1n.ai/v1`	服务地址，界面中显示为默认 Base URL

两个字段在表单中分别以"密码框"（type: 'password'）和普通文本框的形式呈现，对应的表单标签、占位文案均由国际化系统提供（见 zh-Hans/settings.yaml，其中 n1n 的描述文案为"n1n.ai - 高性能的 AI API 提供商"）。

第一步：准备服务访问方式

在 AIRI 中配置之前，先要确认你的 n1n 服务访问信息：

打开并登录 n1n 的服务站点（n1n.ai），确认你的服务地址以及当前服务是否需要 API Key。
如果你的 n1n 部署允许匿名访问（即无需凭据即可调用），则确认该访问策略，后续在 AIRI 中按部署方说明将 API Key 留空。

凭据安全警告即使 API Key 为可选项，也不要公开你的私有服务地址、访问令牌或网关配置。服务地址与凭据一旦泄露，任何拿到信息的人都能调用你的模型额度。

第二步：在 AIRI 中配置 n1n

打开设置 → 服务商 → 聊天 → n1n。默认 Base URL 为https://api.n1n.ai/v1/。
按 n1n 当前服务要求填写 API Key；如果你的部署允许匿名访问，则按部署方说明保留为空。

这里有一个与源码相关的细节：界面展示的默认 Base URL 带尾部斜杠（https://api.n1n.ai/v1/），而源码中的 schema 默认值是https://api.n1n.ai/v1（不带斜杠）。两者均可正常工作——校验器在构造模型列表请求时会自动兼容斜杠情况（见下文"验证机制"）。若你手动修改 Base URL，建议保持以/v1结尾的标准 OpenAI 兼容路径格式。

为什么 API Key 可以是可选项

从源码实现看，apiKey与baseUrl均为可选字段，但服务商还定义了validationRequiredWhen(config) => !!config.apiKey?.trim()，也就是说：仅当填入了非空 API Key 时，才强制要求通过配置验证；留空时（匿名访问场景）则跳过强制校验。这与文档中"如果部署允许匿名访问，则保留为空"的指引完全一致。

createProvider(config)最终以createOpenAI(config.apiKey || '', config.baseUrl)构建客户端——匿名场景下以空字符串作为 API Key 传入，具体是否可用取决于 n1n 部署方的访问策略。

第三步：验证配置

配置填写完成后，按以下顺序完成验证与启用：

Ping API：点击此按钮测试网络、服务地址和凭据是否正确。该操作由服务商注册的验证器执行（见下文），会真实请求 n1n 的服务地址。
选择模型：测试成功后，从模型列表中选择要使用的模型。
再到设置 → 意识启用该服务商，即可在意识能力中使用 n1n 的模型。

n1n 服务商在服务商注册表中被导入并注册（id: 'n1n'，排序order: 9），其验证器由通用工厂createOpenAICompatibleValidators生成，并启用了三项检查，完整实现见 openai-compatible.ts：

Connectivity（连通性检查）：向{baseUrl}/models发起 GET 请求，若填写了 API Key 则附带Authorization: Bearer <apiKey>头，请求带 10 秒超时；服务端返回 5xx 或网络错误时判定失败（对应 openai-compatible.ts）。
ModelList（模型列表检查）：调用模型列表接口，若返回的模型列表为空则判定失败（对应 openai-compatible.ts）。这解释了"测试成功后即可选择模型"的流程——模型下拉选项正是来自该接口。
ChatCompletions（聊天补全检查）：自动从模型列表挑选一个可用模型，发送一条内容为ping的测试消息（max_tokens: 16），验证真实对话链路是否可用（对应 openai-compatible.ts）。

除此之外，服务商还注册了配置格式校验（check-config）：校验 Base URL 必须是合法的绝对 URL（new URL可解析且包含 host），以及"填写了 API Key 时不能为空"等规则（见 openai-compatible.ts）。同类的 OpenAI 兼容校验器在provider-inference包内被大量服务商复用，并有对应的校验器测试覆盖，n1n 的"Ping API"按钮正是这套校验体系的入口。

排查：验证失败怎么办

验证失败时，按以下顺序排查：

服务地址：确认 Base URL 是否填写正确、可从运行 AIRI 的设备访问。注意连通性检查会真实请求{baseUrl}/models，如果该地址在目标网络不可达（如内网网关、需代理的地址），会直接报网络错误。
API Key：确认凭据是否有效、是否过期。留意validationRequiredWhen逻辑——一旦填写了 API Key 就会走完整的三项检查，错误的 Key 会在聊天补全检查中失败；若服务允许匿名访问，则按部署方说明将 API Key 留空，不要填入无效字符串。
访问策略：确认 n1n 部署方当前是否对该地址、该模型开放访问，包括模型白名单、匿名策略、限流等限制。

另外需注意一个校验器的行为细节：聊天补全检查会先尝试拉取模型列表并自动挑选一个模型（跳过embed、tts等非聊天模型）进行探测。如果 n1n 当前没有可用的聊天模型，校验会失败并提示"没有可用于验证的模型，请手动配置模型后重试"。此时应先在服务商配置中手动指定模型，再重新执行 Ping 验证。