在 AIRI 中配置 Featherless.ai 聊天模型API Key、Base URL 与意识系统接入完整指南【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiFeatherless.ai 以兼容 API 的形式向 AIRI 提供云端聊天模型适合已经开通 Featherless.ai 模型访问、希望通过其 API Key 快速让 AIRI「意识」系统获得 LLM 能力的用户。本文以 featherless.md 为主线完整覆盖从获取 API Key、填写服务商配置、Ping API 验证到在「意识」页面启用模型的全部步骤并结合仓库中 provider-inference 的源码实现讲清每一步背后的校验逻辑与参数含义。读完后你将能独立完成 Featherless.ai 的接入、排障并理解 AIRI 服务商注册机制defineProvider、校验器管线的底层原理。Featherless.ai 在 AIRI 中的接入方式Featherless.ai 在 AIRI 中并非独立实现协议而是通过「OpenAI 兼容 API」的方式接入。仓库中对应的服务商定义位于 packages/provider-inference/src/providers/cloud/featherless-ai/index.ts其核心信息如下配置项值说明服务商 IDfeatherless-ai供内部注册表与状态存储使用显示名称Featherless.ai在设置界面与本地化文案中展示任务类型chat仅用于聊天意识任务不涉及 TTS/STT能力chat.reasoning模式enabled/disabled支持显式控制模型「思考」开关图标i-lobe-icons:featherless-color设置目录中的品牌图标归属标签paidCloud付费 / 云端见 packages/stage-ui/src/libs/providers/attributes.ts 与其中的featherless-ai: paidCloud映射服务商定义通过defineProvider注册注册表 中导入了providerFeatherlessAI。其配置模式zod schema明确了两项参数const featherlessConfigSchema z.object({ apiKey: z.string(API Key), baseUrl: z .string(Base URL) .optional() .default(https://api.featherless.ai/v1/), })也就是说API Key 为必填Base URL 可选且代码中内置了默认值https://api.featherless.ai/v1/。这与设置界面里「默认 Base URL」的说法完全一致——即使你不填 Base URL也会回退到该默认地址。在运行时createProvider(config)通过createOpenAI(config.apiKey, config.baseUrl)构造 OpenAI 兼容客户端所有请求走标准 OpenAI Chat Completions 协议。第一步获取 Featherless.ai API Key登录 Featherless.ai 账户进入账户控制台Dashboard创建 API Key。创建后立即妥善保存页面关闭后通常无法再次查看完整 Key。::: warning API Key 安全 不要将 API Key 提交到仓库、截图或发送给他人。在 AIRI 中Key 存储在本地凭据中且输入框以密码形式展示见 step-provider-configuration.vue 中typepassword的 API Key 输入项。 :::第二步在 AIRI 服务商设置中填写凭据打开设置 → 服务商 → 聊天 → Featherless.ai填写API Key。Base URL 保持默认值https://api.featherless.ai/v1/即可仅当你使用自建代理或网关时才需要修改。界面上 API Key 输入框的占位符为fw-...见 step-provider-configuration.vue提示 Key 的常见前缀格式Base URL 输入框会自动填充该服务商defaultConfig中的默认 Base URL同文件getBaseUrlPlaceholderL211-L216。如果你使用引导式Onboarding配置流程填写完 API Key 后还可以勾选「Chat Ping Check」选项控制是否在验证阶段实际发起一次聊天请求该选项仅在服务商配置了手动校验器时出现Featherless.ai 满足此条件。这一步对应的 UI 逻辑与校验入口都集中在上述组件中handleNext()会调用providersStore.validateProviderConfig完成验证只有验证通过才允许进入下一步。第三步验证配置Ping API 与校验管线在服务商配置页点击Ping APIAIRI 会执行一套「OpenAI 兼容服务商」的通用校验管线。Featherless.ai 启用的检查项在源码中明确声明validators: { ...createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions], }), },对应 packages/provider-inference/src/types.ts 中的枚举与 packages/provider-inference/src/validators/openai-compatible.ts 的实现按顺序依次执行配置自检check-config检查 API Key 非空、Base URL 非空且必须是合法的绝对 URL会调用new URL()解析并校验 host。连通性检查check-connectivity向{baseUrl}/models发起带Authorization: Bearer apiKey的 GET 请求超时 10 秒自动中止仅当返回 HTTP 5xx 或网络层异常时判定失败。这一步就是「Ping API」按钮的核心动作用于确认网络连通与 Key 有效性。模型列表检查check-model-list拉取模型列表并确认非空供后续「选择模型」使用。聊天补全检查check-chat-completions用选中的模型发送一条内容为ping的用户消息max_tokens固定为 16源码注释说明部分 OpenAI 兼容服务商不接受低于 16 的输出上限。该检查结果会带缓存与互斥锁避免重复触发消耗配额。一个值得注意的实现细节AIRI 在后台/自动校验时会主动跳过聊天补全检查因为这类探测会消耗 API 配额应当只由用户显式操作例如点击「Ping API」按钮触发。相关逻辑见 packages/stage-ui/src/stores/providers/provider.ts其中skipChatPingCheck: true以及源码注释明确说明了这一设计意图。因此在手动 Ping 时你获得的是包括真实对话探测在内的完整校验结果。第四步选择模型并在「意识」中启用Ping API 测试成功后在服务商配置中选择模型模型列表即来自上一步的 ModelList 检查结果。进入设置 → 意识在「意识 / 模型」区域为该角色选择已配置的 Featherless.ai 模型并启用。「意识」页面对应 packages/i18n/src/locales/zh-Hans/settings.yaml 的consciousness文案提供以下能力模型选择器展示服务商返回的模型列表支持关键字搜索搜索文案为「找到 {count} / {total} 个模型」如果服务商不支持列出模型会显示「无法列出模型」的提示。手动输入模型名当列表不可用或你想使用精确模型 ID 时可在「模型名字 / 输入自订模型名称」中直接填写 Featherless.ai 提供的精确模型 ID绕过列表加载问题。采样参数温度temperature如 0.2 更确定、1.0 更多样与 Top P核采样可调。思考开关Thinking在「模型选项」下可切换思考模式。关于思考开关Featherless.ai 服务商在源码层面对其做了专门处理index.tschat(model: string, options?: ChatRequestOptions) { const request provider.chat(model) if (!options?.reasoning) return request return { ...request, chatTemplateKwargs: { enable_thinking: options.reasoning enabled } } }即当你把该模型的推理能力设为enabled时请求会携带enable_thinking: true模板参数设为disabled时则为false。这解释了为什么该服务商的能力声明为reasoning: { modes: [enabled, disabled] }——它通过模板注入而非参数透传的方式控制模型是否输出思考链。排查指南Ping API 失败结合校验管线的失败分支逐项排查API Key 错误或已失效检查是否复制完整含前缀、账户是否仍有有效额度/访问权限。校验器对 401/403 类响应会归入失败并给出错误原因。账户状态异常确认 Featherless.ai 账户未欠费、模型访问未被限制。网络连接连通性检查是对{baseUrl}/models的 10 秒超时请求网络代理、DNS、防火墙问题都会导致失败。确认当前网络能直连https://api.featherless.ai/v1/。模型列表无法加载确认 Base URL 保持默认值https://api.featherless.ai/v1/不要追加多余路径或缺少结尾的/校验器会把{baseUrl}/models拼接为models端点URL 格式错误会直接导致 4xx 或 5xx。若列表接口确实异常可在「意识」页面的模型选择区手动输入 Featherless.ai 提供的精确模型 ID绕过列表加载依赖。自动校验与手动校验的差异若你在非显式操作场景如应用启动后的后台校验看到状态为「未配置」或「无效」注意后台校验默认跳过了 Chat Completions 探测见上文第三步这只影响「是否实际发起一次对话」的判定不表示网络或 Key 有问题——此时回到服务商配置页手动点击一次 Ping API 即可获得完整结论。相关源码索引服务商定义与配置模式packages/provider-inference/src/providers/cloud/featherless-ai/index.ts服务商注册导入packages/provider-inference/src/providers/index.ts校验检查项枚举packages/provider-inference/src/types.tsOpenAI 兼容校验管线实现packages/provider-inference/src/validators/openai-compatible.ts服务商目录标签付费/云端packages/stage-ui/src/libs/providers/attributes.ts配置引导表单与 Ping 校验 UIpackages/stage-ui/src/components/scenarios/dialogs/onboarding/step-provider-configuration.vue后台校验与「跳过 Chat Ping」逻辑packages/stage-ui/src/stores/providers/provider.ts「意识」页面本地化文案模型选择、温度、Top P、思考packages/i18n/src/locales/zh-Hans/settings.yaml【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考