AI

AI 模块通过 TanStack AI 和 Cloudflare Workers AI 提供端到端的 AI 能力，并与 TanStack AI 的 fal 适配器 (@tanstack/ai-fal) 深度集成，实现图片生成和图片编辑的能力。

设置

所有 Workers AI 调用均通过 REST API 进行，因此无须配置 Workers Binding，在 CI 等运行环境中同样可以运行。

技术栈

目录结构

src/api/
└── ai.ts                       # 10 个服务器函数 + 辅助函数

src/lib/
└── web-search.ts               # 搜索提供商、输入与结果校验

src/routes/(pages)/
└── ai.tsx                      # AI playground 页面

src/components/ai/
├── ai-web-search-card.tsx      # 网页搜索 (Ceramic.ai / Exa / Linkup)
├── ai-decision-card.tsx        # Clef / Clef Flash
├── ai-summarization-card.tsx   # 文本摘要 (Gemma 4)
├── ai-translation-card.tsx     # 翻译 (m2m100, 10 种语言)
├── ai-tagline-card.tsx         # 标语生成器 (Gemma 4 chat)
├── ai-tts-card.tsx             # 语音合成 (Deepgram Aura 2, 8 种音色)
├── ai-caption-card.tsx         # 图像描述生成 (Gemma 4)
├── ai-cf-image-card.tsx        # 图像生成 · Workers AI (FLUX.2 Klein 4B / 9B, Flux Schnell)
├── ai-image-card.tsx           # 图像生成 · fal.ai (Gemini / Flux / GPT Image 2)
├── ai-image-edit-card.tsx      # 图像编辑 · fal.ai (头像风格化)

模型配置

模型、默认选项与 TTS 音色统一在 src/config/ai-models.ts 配置。摘要、标语与图像描述使用 Gemma 4，翻译使用 m2m100，语音使用 Aura 2。Workers AI 图像生成支持 FLUX.2 Klein 4B/9B 与 Flux Schnell；FLUX.2 请求使用 multipart 输入。fal.ai 提供 Flux Schnell、Nano Banana、GPT Image 2 与 Nano Banana 图像编辑。

AI 能力概览

AI 模块内置了以下开箱即用的 AI 功能，每个功能均提供独立的 UI 卡片组件：

网页搜索

在模板的 /ai#web-search 页面，选择 Ceramic.ai（默认）、Exa 或 Linkup，输入搜索问题，或加载旅行、英语学习、晚餐三个预设示例。查询去除首尾空格后须为 1–1024 字符。页面展示编号、标题与来源链接；修改查询或切换提供商会清除旧结果，失败后可重试。

使用前配置 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN，令牌需同时具有 Workers AI > Read 与 AI Gateway > Read 权限。还需充值 AI Gateway credits，或在 default 网关为所选搜索提供商保存 API Key（使用 default 别名）。无需新增 Exa、Linkup 的项目环境变量，也不依赖 FAL_KEY。配置步骤见 Cloudflare Web Search API 官方文档。

searchWeb 向 /accounts/{account_id}/ai/websearch/ 发送 REST 请求，固定使用 default AI Gateway，设置 limit: 5 和 30 秒超时。HTTP 402 会提示需要网关额度或提供商密钥。UI 位于 src/components/ai/ai-web-search-card.tsx，服务器函数位于 src/api/ai.ts，提供商列表与输入、结果校验位于 src/lib/web-search.ts。

tests/e2e/specs/ai-web-search.spec.ts 覆盖预设、提供商切换、输入校验、失败重试和 Mock 来源链接展示；这些测试不能证明真实搜索服务可用，详见自动化测试。

文本处理

• 文本摘要 — 将长文章压缩为简洁摘要，输入 50–500 字符即可获得精炼概括。
• 文本翻译 — 支持 10 种语言之间的多语言互译，提供一键交换按钮快速切换源语言和目标语言。
• 标语生成器 — 输入产品描述，自动生成 5 条营销标语，适合快速产出品牌文案。

语音与图像理解

• 语音合成（TTS） — 将文本转为自然语音，提供 8 种 Aura 2 音色（Asteria、Luna、Athena、Hera、Arcas、Orion、Orpheus、Zeus），返回 MP3 音频。
• 图像描述生成 — 上传图片后自动生成描述文本，支持多种预设提示词风格（简短描述、详细描述、关键词提取等）。

图像生成与编辑

• 图像生成 · Workers AI — 通过 Cloudflare Workers AI 生成图像，支持多种风格模型（FLUX.2 Klein 4B/9B、Flux Schnell）。
• 图像生成 · fal.ai — 通过 fal.ai 生成高质量图像，覆盖从快速廉价到高端逼真的多档模型。
• 头像风格化 — 上传人像照片，一键转换为多种风格（摇头娃娃、Pixar 3D、动漫头像等），同时保留人物特征。

Clef 决策演示

/ai#decision-model 提供 Clef 与 Clef Flash 支持工单决策演示。输入工单或选择预设后，evaluateTicket 向 Workers AI 提交状态与三个类型化问题，返回紧急程度、团队概率与严重程度。组件为 src/components/ai/ai-decision-card.tsx，问题和返回校验位于 src/lib/clef.ts。输入需为 10–4000 字符。

浏览器测试使用 Mock 验证交互与错误恢复，真实模型输出需另行验证，详见自动化测试。

相关文档