AIRI 接入 Cloudflare Workers AI 完整指南账号级凭证配置、校验机制与源码解析【免费下载链接】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本指南讲解在 AIRI 中配置Cloudflare Workers AI聊天模型提供商的完整流程。与多数只需 API Key 的 OpenAI 兼容服务不同Cloudflare Workers AI 使用账号级凭证API Token Account ID本文将从凭证准备、界面配置、配置校验原理到运行时工具调用降级机制结合仓库源码给出可复现的实战方案。读完你将掌握如何让 AIRI 通过自有 Cloudflare 账号调用 Workers AI 模型并能依据源码理解每一步校验的真实行为边界。为什么选择 Cloudflare Workers AICloudflare Workers AI 是运行在 Cloudflare 全球边缘网络上的模型推理服务通过你的 Cloudflare 账号直接使用受支持的 Workers AI 模型。AIRI 将其作为聊天chat类提供商接入区别于需要手动填写 Base URL 的 OpenAI 兼容提供商——Workers AI 的地址由账号信息推导得出不提供可编辑的 Base URL 字段。从源码看该提供商的注册信息位于 providers/cloudflare-workers-ai/index.tsid: cloudflare-workers-ai能力标记为tasks: [chat]描述为 Cloudflare Workers AI with account-scoped credentials.账号级凭证在提供商目录中标记为paid cloud类别见 attributes.ts并配有 Cloudflare 品牌图标。准备凭证API Token 与 Account IDCloudflare Workers AI 需要两项账号级信息缺一不可打开 Cloudflare API Tokens 页面创建一个具备 Workers AI 访问权限的 API Token并复制该 Token。在 Cloudflare Console 中找到并复制你的Account ID。::: warning 安全提醒 API Token 与账号权限绑定。请遵循最小权限原则仅为 AIRI 授予其所需的 Workers AI 权限不要使用拥有整个账号管理权限的 Token。切勿将 Token 或 Account ID 写入公开日志或提交到公共仓库。 :::在 AIRI 中配置提供商打开Settings → Providers → Chat → Cloudflare Workers AI。填写API Token和Account ID两个字段。对应的配置页面源码位于 chat/cloudflare-workers-ai.vue注意仓库中为packages/stage-pages/src/pages/settings/providers/chat/cloudflare-workers-ai.vue页面由通用设置组件组成ProviderApiKeyInputAPI Token 输入框字段类型为password占位提示 Input Cloudflare API KeyProviderAccountIdInputAccount ID 输入框占位提示 Your Cloudflare Account ID两个字段的值通过providers.value[providerId].apiKey/.accountId存入提供商配置 store持久化于本地。对应字段定义与多语言文案见 settings.yamlcloudflare-workers-ai: description: cloudflare.com fields: field: account-id: description: Cloudflare Account ID label: Account ID placeholder: Your Cloudflare Account ID api-key: placeholder: Input Cloudflare API Key title: Cloudflare Workers AI校验必须字段的触发条件在 index.ts 中validationRequiredWhen决定何时激活校验逻辑validationRequiredWhen: (config) { return !!config.apiKey !!config.accountId },即只有当API Token 与 Account ID 均已填写时才触发字段校验——两者任一为空都不会进入校验流程。验证配置两类校验的真实边界AIRI 对 Cloudflare Workers AI 的配置验证分两个层面理解其边界可避免误判。必填字段自动检查本地校验不联网配置页面挂载ProviderValidationAlerts组件展示校验状态。底层校验器定义在 index.ts 的validateConfig中validator: async (config) { const errors: Array{ error: unknown } [] const apiKey typeof config.apiKey string ? config.apiKey.trim() : const accountId typeof config.accountId string ? config.accountId.trim() : if (!apiKey) errors.push({ error: new Error(API token is required.) }) if (!accountId) errors.push({ error: new Error(Account ID is required.) }) // ... }关键事实由源码确认校验前会trim()去除首尾空白因此仅含空格的字符串会被判定为空校验只确认两个字段是否有值不会请求 Cloudflare、不会验证 Token 权限、不验证 Account ID 是否真实存在校验通过仅表示“字段已填写”并不代表凭证有效。实际连通性测试发送测试消息要真正验证凭证有效性须走完整链路等待必填字段自动检查通过isValid为真点击Select Model →跳转到Settings → Modules → Consciousness模块在模型选择中选中Cloudflare Workers AI及一个可用模型返回聊天界面发送一条测试消息。只有收到成功响应才能确认Account ID、API Token 权限与所选模型三者协同工作。UI 中 Select Model 按钮的跳转目标在 chat/cloudflare-workers-ai.vue 中写死为/settings/modules/consciousness。运行时的底层调用createWorkersAI当聊天请求真正发起时AIRI 通过createProvider构造底层聊天客户端index.tscreateProvider(config) { return createWorkersAI(config.apiKey, config.accountId) },createWorkersAI来自xsai-ext/providers/special/create它接收 API Token 与 Account ID据此推导出 Workers AI 的完整请求地址与鉴权头。这就是文档中“本提供商不使用可编辑 Base URL不要填写 Worker URL 或 API 路径”的源码依据——URL 由账号信息内部合成手动覆盖会导致请求失败。工具调用能力的自动降级Cloudflare Workers AI 的部分模型不支持工具调用function calling。AIRI 在运行时对这类错误有专门的自动降级处理见 llm-service.tsconst TOOLS_RELATED_ERROR_PATTERNS: RegExp[] [ // ... /tools?\s(is|are)\snot\ssupported/i, // Cloudflare Workers AI ]当来自 Cloudflare 的错误消息匹配该模式如 tools is not supported、tool is not supported for this modelAIRI 会判定当前模型不支持工具调用并自动降级为纯文本对话模式。这一行为有测试用例佐证llm.test.ts[cloudflare, tools is not supported], [cloudflare, tool is not supported for this model], [cloudflare, tools are not supported],这意味着即使你在聊天中启用了 AIRI 的内置工具如搜索、记忆等遇到不支持工具的 Workers AI 模型时AIRI 也会优雅地忽略工具、只发送普通消息而不是直接报错中断。多模态延伸视觉模块复用同一凭证同一组 Cloudflare 账号凭证还可用于 AIRI 的视觉Vision模块。仓库中提供了独立的配置页 vision/cloudflare-workers-ai.vue其 providerId 为vision-cloudflare-workers-ai字段仍为 API Token Account ID校验与跳转逻辑同聊天版一致跳转目标为/settings/modules/vision。如果你使用支持视觉的 Workers AI 模型可在Settings → Providers → Vision中复用这组凭证。故障排查指南现象可能原因处理方式必填字段检查未通过API Token 或 Account ID 为空/仅含空白确认两个字段都填写了非空值校验前会 trim测试消息失败Token 没有 Workers AI 权限回到 Cloudflare API Tokens 页面确认 Token 授予了 Workers AI 相关权限测试消息失败Account ID 与 Token 不属于同一账号确认 Account ID 与 Token 来自同一个 Cloudflare 账号请求 404 / 路径错误在配置中填入了 Worker URL 或 API 路径删除多余 URL——该提供商不使用 Base URL 字段地址由 Account ID 自动推导模型返回工具类错误所选模型不支持工具调用无需干预AIRI 会自动降级为无工具模式或更换支持工具调用的模型总结Cloudflare Workers AI 在 AIRI 中的接入要点可归纳为三条凭证账号级 API Token Account ID两者必须同属一个 Cloudflare 账号且 Token 遵循最小权限原则配置Settings → Providers → Chat → Cloudflare Workers AI仅填写两个字段本地必填校验不联网真实连通性需通过 Consciousness 模块选模型后发送测试消息确认运行时请求地址由createWorkersAI(apiKey, accountId)内部推导无需 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/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考