Cloudflare Workers AI Provider 接入（Phase 1）：Kiln 后端适配与连接校验全解析

人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载导读本文基于 Kiln 仓库中 Cloudflare Workers AI Provider 项目的 Phase 1 实施计划phase_1.md完整讲解将 Cloudflare Workers AI 接入 Kiln 的后端技术方案包括ModelProviderName枚举扩展、三项新配置项、基于 LiteLLM 通用openai/路由的适配器接入、按账号 ID 动态生成的 base URL、可选的 AI Gateway 请求头以及连接/断开 API 的两步连接校验流程和 Web 前端管线schema、名称映射、图片映射、Logo。读完本文你将掌握 Kiln 新增一个云侧 AI Provider 的标准接入范式并能在仓库源码与测试用例中找到每一处实现的落点。一、Phase 1 目标与整体设计Phase 1 是接入 Cloudflare这条项目主线中的后端与 Web 基础设施阶段。它的核心诉求非常克制让 Cloudflare 成为一个标准供应商——不引入任何超出其他 Provider 已有的 UX一切接入都复用 Kiln 现有的通用机制。从 phase_1.md 的 Overview 可以提炼出三条设计主线走 LiteLLM 通用路由Cloudflare 不单独走cloudflare/专用路由而是作为一个自定义 Provider运行在 LiteLLM 的通用openai/路由上。这样做的直接原因是LiteLLM 内置的cloudflare/provider 会丢弃大部分请求参数和网关头源码中对此有明确注释见下文无法满足 Kiln 对 AI Gateway 支持的需求。账号级 base URL 可选网关头Cloudflare Workers AI 的 REST API 按账号Account隔离因此 base URL 必须根据cloudflare_account_id动态生成如果用户配置了 AI Gateway则额外携带cf-aig-gateway-id请求头。两步连接校验连接 API 不是填了就算连上而是先调用模型搜索接口校验 Token/账号/权限再仅当填写了网关 ID 时用一次假模型的 chat 调用校验网关是否存在。此外新增枚举值会在 Web 侧强制产生一系列管线改动API schema 重新生成、provider 名称映射、图片映射与 Logo 文件这些统称 web plumbing。以下按 Phase 1 的实施步骤顺序逐文件展开源码级分析。二、Provider 枚举扩展datamodel_enums.py第一步是在核心数据模型中声明新的 Provider 枚举值。修改位于 libs/core/kiln_ai/datamodel/datamodel_enums.pyModelProviderNamestr, Enum在featherless_ai之后新增featherless_ai featherless_ai cloudflare cloudflare typesafe typesafe实际仓库中该枚举位于 datamodel_enums.py 的ModelProviderName类cloudflare cloudflare紧随featherless_ai第 136 行。ModelProviderName是 Kiln 全链路配置、适配器、Provider 工具、连接 API、Web schema共享的供应商标识新增枚举值即会在类型层面驱动后续所有分支必须补齐 Cloudflare 的处理这正是 Overview 中新增枚举值强制产生 web plumbing的原因。三、三项新配置项utils/config.py第二步在 Kiln 的统一配置中心注册 Cloudflare 的三个配置键位置在 Fireworks 相关条目之后libs/core/kiln_ai/utils/config.py配置键环境变量sensitive说明cloudflare_api_keyCLOUDFLARE_API_KEYTrueWorkers AI API Token敏感持久化时脱敏cloudflare_account_idCLOUDFLARE_ACCOUNT_IDFalse账号 ID用于拼装 base URLcloudflare_ai_gateway_idCLOUDFLARE_AI_GATEWAY_IDFalseAI Gateway ID可选实现上每个键都是ConfigProperty(str, env_var..., sensitive...)形式只有 API Token 被标记为sensitiveTrue。对应的配置项测试是test_config.py::test_cloudflare_propertieslibs/core/kiln_ai/utils/test_config.py它参数化校验了三个键的类型、环境变量名与敏感标志。四、LiteLLM 适配器接入utils/litellm.py第三步决定 Cloudflare 在 LiteLLM 层的路由方式。libs/core/kiln_ai/utils/litellm.py 中的分支如下case ModelProviderName.cloudflare: # LiteLLMs built-in cloudflare/ provider drops most request params and the gateway header is_custom True这里把cloudflare标记为自定义 Provideris_custom True意味着它不会使用 LiteLLM 内置的cloudflare/provider 名而是落到openai/通用路由上。源码注释说明了原因LiteLLM 内置的 cloudflare provider 会丢弃大部分请求参数和网关头。LiteLLM 模型 ID 的生成逻辑由测试test_cloudflare_model_id_keeps_cf_prefixlibs/core/kiln_ai/utils/test_litellm.py锁定Cloudflare 模型 ID如cf/zai-org/glm-5.3在openai/前缀下保留cf/前缀最终 LiteLLM 模型 ID 为openai/cf/zai-org/glm-5.3。同时test_litellm_adapter.py::test_litellm_model_id_standard_providers参数表中也有(cloudflare, openai)一项印证了 provider 映射关系。五、Provider 工具层base URL、网关头与核心配置第四步是本次接入的中枢——libs/core/kiln_ai/adapters/provider_tools.py。它包含四类改动5.1 名称与警告provider_name_from_id的枚举分支返回Cloudflareprovider_tools.py。provider_warnings[cloudflare]只要求两个必填键ModelProviderName.cloudflare: ModelProviderWarning( required_config_keys[cloudflare_api_key, cloudflare_account_id], messageAttempted to use Cloudflare without an API token and account ID set. \nCreate a token and find your account ID at https://dash.cloudflare.com/?to/:account/ai/workers-ai, ),注意网关 ID 不是必填项这由测试test_cloudflare_provider_warning_requires_key_and_account_not_gateway明确锁定test_provider_tools.py。provider_enabled的判定也遵循同样逻辑只有 API Token 和 Account ID 同时存在才视为启用test_provider_enabled_cloudflaretest_provider_tools.py。5.2 模块级常量与 URL/Headers 辅助函数CLOUDFLARE_API_BASE https://api.cloudflare.com/client/v4 CLOUDFLARE_GATEWAY_HEADER cf-aig-gateway-id def cloudflare_base_url(account_id: str) - str: return f{CLOUDFLARE_API_BASE}/accounts/{quote(account_id, safe)}/ai/v1 def cloudflare_headers(gateway_id: str | None) - Dict[str, str] | None: return {CLOUDFLARE_GATEWAY_HEADER: gateway_id} if gateway_id else None见 provider_tools.py。几个关键细节Account ID 必须 URL 编码使用urllib.parse.quote(..., safe)对路径中的/、?等字符全部编码防止账号 ID 注入 URL 路径。测试test_cloudflare_base_url_encodes_path_characters验证了a/b?c会被编码为a%2Fb%3Fctest_provider_tools.py。网关头只在有网关 ID 时出现cloudflare_headers(None)与cloudflare_headers()均返回None只有非空字符串才返回{cf-aig-gateway-id: gw}test_cloudflare_headers参数化覆盖None//gw三种情况。5.3 核心配置组装_cloudflare_core_configdef _cloudflare_core_config() - LiteLlmCoreConfig: account_id Config.shared().cloudflare_account_id if not account_id: raise ValueError(provider_warnings[ModelProviderName.cloudflare].message) return LiteLlmCoreConfig( base_urlcloudflare_base_url(account_id), default_headerscloudflare_headers(Config.shared().cloudflare_ai_gateway_id), additional_body_options{api_key: Config.shared().cloudflare_api_key}, )provider_tools.py。要点账号 ID 缺失时直接抛出ValueError消息即 provider warning 文案。测试test_lite_llm_core_config_for_provider_cloudflare_missing_account对None与两种情形断言了该异常test_provider_tools.py。base URL 按账号动态生成default_headers只在配置了网关时携带cf-aig-gateway-idAPI Token 通过additional_body_options以api_key字段注入请求体。lite_llm_core_config_for_provider中对应分支直接返回该配置provider_tools.py。test_lite_llm_core_config_for_provider_cloudflare参数化验证了带/不带网关两种情况下的完整配置结构test_provider_tools.py。5.4 适配器创建验证在适配器注册层面test_adapter_registry.py::test_cloudflare_adapter_creationlibs/core/kiln_ai/adapters/test_adapter_registry.py使用模型cf/zai-org/glm-5.3创建适配器断言其为LiteLlmAdapter且 base URL 为https://api.cloudflare.com/client/v4/accounts/test-cloudflare-account/ai/v1default_headers随网关 ID 有无而变化additional_body_options携带 API key。六、连接/断开 API两步连接校验第五步位于桌面端 Studio 服务器的 app/desktop/studio_server/provider_api.py。它实现了最核心的用户侧功能连接 Cloudflare 与断开 Cloudflare。6.1 字段与常量CLOUDFLARE_TOKEN_FIELD API Token CLOUDFLARE_ACCOUNT_FIELD Account ID CLOUDFLARE_GATEWAY_FIELD AI Gateway ID - Optional CLOUDFLARE_CONNECTION_CHECK_MODEL cf/kiln/connection-check CLOUDFLARE_NO_SUCH_MODEL_CODE 5007 CLOUDFLARE_GATEWAY_NOT_FOUND_CODE 2001 CLOUDFLARE_CONNECT_TIMEOUT_SECONDS 30provider_api.py。字段标签与 Phase 2 UI 中的输入框一一对应两个错误码分别表示模型不存在5007与网关不存在2001所有连接校验请求的 HTTP 超时统一为 30 秒。辅助函数_cloudflare_field(key_data, field)取值、要求字符串、strip()后空串转Noneprovider_api.py。_cloudflare_error_codes(response) - set[int]从响应 JSON 的errors列表提取错误码集合非 JSON 响应返回空集provider_api.py。_cloudflare_connect_error(status_code, detail)与_cloudflare_unexpected_response(response)统一拼装Failed to connect to Cloudflare. ...错误响应provider_api.py。6.2connect_cloudflare两步校验流程函数签名是connect_cloudflare(key_data: dict)——注意它接收完整 dict而非单个字符串键这一点与大多数 Provider 不同见 provider_api.py。整体流程第 0 步必填校验。Token 或 Account ID 任一缺失/空/非字符串立即返回 400API Token and Account ID are required.不发起任何请求。第 1 步模型搜索校验。发起GET https://api.cloudflare.com/client/v4/accounts/{quote(account_id, safe)}/ai/models/search?searchkiln-connection-check Authorization: Bearer {token}搜索词故意选一个不存在的模型名kiln-connection-check让响应体保持极小但请求本身仍能完整校验三件事Token 有效性、Account ID 有效性、该 Token 是否具备 Workers AI 访问权限。响应映射状态码用户侧响应404401Invalid Account ID.400 / 401 / 403401Invalid API Token, or the token doesnt have Workers AI access for this Account ID.其他非 200400 通用错误附[status] text此分支由test_connect_cloudflare_search_failures参数化覆盖test_provider_api.py任何失败都不会发起网关调用、不会保存配置。第 2 步可选网关校验。仅当用户填了网关 IDstrip后非空才执行POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1/chat/completions Headers: Authorization: Bearer {token}, cf-aig-gateway-id: {gateway_id} Body: {model: cf/kiln/connection-check, messages: [{role: user, content: ping}], max_tokens: 1}设计精妙之处在于模型搜索接口会忽略网关头所以网关必须用一次真实 chat 调用来探测而 Cloudflare 会在解析模型之前先拒绝不存在的网关且由于这个假模型必然不存在无论如何都不会真的跑推理。响应映射错误码含2001网关不存在→ 400AI Gateway {gateway_id} not found. Check the gateway ID, or remove it.不保存。200或错误码含5007模型不存在但网关本身有效→ 校验通过。其他含非 JSON、502、意外错误码如 10000→ 400 通用错误不保存。第 3 步全通过后才落盘。Config.shared().update_settings一次性写入三个键{ cloudflare_api_key: token, cloudflare_account_id: account_id, cloudflare_ai_gateway_id: gateway_id, # 未填时写入 None并清除旧值 }整个函数包在try/except中任何异常网络错误、超时等统一转为 400Error: {str(e) or type(e).__name__}。测试矩阵对上述每条路径都有精确断言包括Account ID 在搜索 URL 中被 URL 编码a/b?c→a%2Fb%3Fctest_provider_api.py未填网关时精确的搜索请求、不发起 chat 调用、网关字段写入Nonetest_provider_api.py网关 200/5007 与 2001 两种分支的精确 chat 请求体与保存行为test_provider_api.py非 JSON 502 与意外错误码test_provider_api.py连接异常ConnectError/ReadTimeout的 400 响应test_provider_api.py。6.3 分发与断开connect_api_key的分发分支为case ModelProviderName.cloudflare: return await connect_cloudflare(key_data)传入完整 dictprovider_api.py分发测试断言connect_cloudflare以完整key_data被调用test_provider_api.py。断开发起时同时清空三个字段cloudflare_api_key、cloudflare_account_id、cloudflare_ai_gateway_id全部置Noneprovider_api.py且不影响其他 Provider 的配置test_disconnect_api_key_cloudflaretest_provider_api.py。cloudflare同时进入了无效载荷参数化测试与mock_config_all_providers全 Provider mocktest_provider_api.py确保接入没有破坏通用的 Provider 连接框架。七、Web 侧管线schema、名称、图片、Logo新增枚举值强制要求 Web 前端四件套同步这是 Phase 1 的收尾step 6API schema 重新生成运行 app/web_ui/generate_schema.sh 重新生成 app/web_ui/src/lib/api_schema.d.ts其中ModelProviderName联合类型已包含cloudflare第 9746 行保证前端类型与后端枚举严格同步。名称映射app/web_ui/src/lib/stores.ts 的provider_name_map增加cloudflare: Cloudflare。图片映射app/web_ui/src/lib/ui/provider_image.ts 增加cloudflare: /images/cloudflare.svg。Logo 文件将规格资产 specs/projects/cloudflare_workers_ai_provider/assets/cloudflare.svg 处理为 app/web_ui/static/images/cloudflare.svg。处理规则明确移除 XML 声明、注释、title、width与height属性将填充色改为fillcurrentColor便于随主题色变化并用 Playwright 的getBBox()测量路径包围盒后裁剪viewBox使 Logo 紧凑且无多余留白。这些改动的可验证性同样来自前端测试connect_providers.test.ts/setup/(setup)/connect_providers/connect_providers.test.ts) 中断言 Cloudflare 行渲染的图片src为/images/cloudflare.svg第 224-225 行。八、运行时行为请求装配与错误分类适配器级测试在 libs/core/kiln_ai/adapters/model_adapters/test_cloudflare_litellm.py 中用respx模拟 HTTP 层并通过litellm.disable_aiohttp_transport True关闭 LiteLLM 默认的 aiohttp 传输以便拦截从适配器视角验证了运行时的关键行为带网关请求命中POST https://api.cloudflare.com/client/v4/accounts/{account}/ai/v1/chat/completions携带cf-aig-gateway-id头、Authorization: Bearer key请求体中的模型为cf/zai-org/glm-4.7-flash保留cf前缀。不带网关请求中没有cf-aig-gateway-id头。限流429 且错误码 3021 → 解包后为litellm.RateLimitError可重试is_retryable_error不判定为批处理致命错误not is_batch_fatal_error错误消息以 Rate limit exceeded 开头该行为在带/不带网关两种情况下都成立。认证失败401 且错误码 10000 →AuthenticationError不可重试批处理致命is_batch_fatal_error。这两类错误分类直接决定了 Kiln 在批量生成/评估任务中对 Cloudflare 限流是重试、认证失败是整体中止的运维策略是接入质量的关键一环。九、总结与后续衔接Phase 1 以最小改动完成了 Cloudflare 的完整后端闭环枚举、配置、LiteLLM 路由、Provider 工具层、连接/断开 API、Web 管线四件套并配套了覆盖每个分支的测试矩阵。其接入范式is_custom True走openai/路由 按账号动态 base URL 可选网关头 两步连接校验可以被后续新增的同类云 Provider 直接复用。UI 侧的用户入口属于 Phase 2连接界面的 Cloudflare 卡片相关实施计划见 phase_2.md整个项目的目标与设计背景可参阅 project_overview.md。核心文件速查枚举libs/core/kiln_ai/datamodel/datamodel_enums.py配置libs/core/kiln_ai/utils/config.pyLiteLLM 路由libs/core/kiln_ai/utils/litellm.pyProvider 工具层libs/core/kiln_ai/adapters/provider_tools.py连接 APIapp/desktop/studio_server/provider_api.py适配器行为测试libs/core/kiln_ai/adapters/model_adapters/test_cloudflare_litellm.py连接 API 测试app/desktop/studio_server/test_provider_api.py赞分享人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载相关推荐Kiln 集成 Cloudflare Workers AI 提供商从连接到推理的完整实现解析Kiln 集成 Cloudflare Workers AI 提供商从连接到推理的完整实现解析 本篇技术指南以 Kiln 仓库中 Cloudflare Work人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用MLOps如何用ytDownloader快速保存任意网站视频完整指南与功能解析如何用ytDownloader快速保存任意网站视频完整指南与功能解析 ytDownloader是一款现代化的跨平台视频/音频下载工具粘贴链接即可从YouTu音视频桌面应用NLWeb 接入 Cloudflare AutoRAG检索后端配置与连通性验证实战指南NLWeb 接入 Cloudflare AutoRAG检索后端配置与连通性验证实战指南 Cloudflare AutoRAG 是 Cloudflare 平台上AI 应用MCP 服务AI Agent后端前端上一篇如何免费实现跨平台Visio文件编辑draw.io桌面版为你带来终极解决方案下一篇B站视频下载终极指南用BiliDownload轻松获取无水印高清视频创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考