在 Netlify 应用中加入 AI 功能时，用 AI…

在 Netlify Functions/Edge Functions 中通过官方 SDK 调用 OpenAI、Anthropic、Gemini、TypeSafe、OpenRouter 模型，无需自管 API Key。

适用场景

解决思路

1. 用各家官方 SDK 并零参数实例化，网关会自动注入凭据：`new OpenAI()`、`new Anthropic()`、`new GoogleGenAI({})`、`new TypeSafeClient()`、`new OpenRouter()`，分别读取 `OPENAI_API_KEY`/`OPENAI_BASE_URL`、`ANTHROPIC_API_KEY`/`ANTHROPIC_BASE_URL`、`GEMINI_API_KEY`/`GOOGLE_GEMINI_BASE_URL`、`TYPESAFE_API_KEY`/`TYPESAFE_BASE_URL`、`OPENROUTER_API_KEY`/`OPENROUTER_BASE_URL`。
2. 不要手写裸 `fetch()` 打网关 URL，也不要把 `NETLIFY_AI_GATEWAY_KEY`/`NETLIFY_AI_GATEWAY_URL` 当作默认路径；这对变量始终被注入且不会与用户自设的 provider 变量冲突，仅在第三方或不支持的库需要显式 key/base-URL 配置时作为构造参数传入。
3. 把调用写在普通 Function/Edge Function 里（没有 AI 专用文件类型）：例如 `netlify/functions/joke.js` 导出 `config = { path: "/api/joke" }`，在 `netlify dev` 和生产环境都映射到 `/api/joke`。
4. Anthropic 用法：`const anthropic = new Anthropic();` 然后 `anthropic.messages.create({ model: 'claude-sonnet-4-5-20250929', max_tokens: 1024, messages: [{ role: 'user', content: 'Hello!' }] })`。
5. OpenAI 用法：`const openai = new OpenAI();` 然后 `openai.chat.completions.create({ model: 'gpt-5', messages: [...] })`。
6. Gemini 用法：`const genAI = new GoogleGenAI({});` 然后 `genAI.models.generateContent({ model: 'gemini-2.5-pro', contents: 'Hello!' })`。
7. TypeSafe（结构化决策，如路由/分类表单提交）：`const client = new TypeSafeClient();` 调用 `client.systemOne({ state: body, questions: { team: choice('Route this contact form submission', { sales: null, support: null, spam: null }) } })`，结果在 `answers.team.choice`；`systemOne` 默认模型 `jev-latest`，每个问题是 `choice(prompt, options)` 把命名选项映射到 `null`，POST JSON body 并带 `Content-Type: application/json`。
8. OpenRouter 用法（需 SDK 1.2.43+）：`const openRouter = new OpenRouter();` 然后 `openRouter.chat.send({ chatRequest: { model: 'x-ai/grok-4.5', messages: [...] } })`；OpenRouter 上的模型也可用 OpenAI SDK 加 OpenRouter 模型 ID（如 `deepseek/deepseek-v4-flash-0731`）作为 `model` 调用。
9. 不要硬编码模型列表，模型会变；查实时 providers 端点 `https://api.netlify.com/api/v1/ai-gateway/providers/detailed`。
10. 不要在浏览器端调用网关——浏览器没有注入凭据，调用只能放在 Functions 或 Edge Functions。
11. 不要在构建脚本、预渲染/SSG 或构建插件里调用网关——这些场景拿不到凭据会失败；AI 工作放在请求时做，若结果需看起来是预计算的则缓存到 Netlify Blobs。
12. 同步函数里的网关调用受 60 秒函数超时限制：长生成要流式（SDK streaming + `ReadableStream`），或用后台函数持久化输出供客户端拉取，绝不能让慢生成不流式地跑。
13. 网关需要至少一次生产部署才会激活；即使本地开发也要先跑一次 `netlify deploy --prod`。
14. 本地开发两种方式（都需先有一次生产部署）：用 `netlify dev` 获得完整网关支持；或用 `@netlify/vite-plugin` 在不用 `netlify dev` 的情况下本地访问网关——在 `vite.config.js` 中 `plugins: [react(), netlify()]` 后跑原生 `npm run dev`。
15. 初始化流程：`npm install -g netlify-cli@latest`、`netlify login`、`npm create vite@latest dad-jokes -- --template react --no-interactive`、`cd dad-jokes && npm install`、`netlify init`、`netlify deploy --prod --open`（激活网关所必需）。
16. 完整示例：先 `npm install openai`，在 `netlify/functions/joke.js` 中先检查 `process.env.OPENAI_BASE_URL` 是否存在以判断网关是否激活，再 `new OpenAI()` 调 `client.responses.create({ model: 'gpt-5-mini', input: [{ role: 'user', content: '...' }], reasoning: { effort: 'minimal' } })`，返回 `res.output_text`、`res.model` 与 `res.usage` 的 token 数；前端 `src/App.jsx` 用 `fetch('/api/joke')` 取结果。
17. 注意凭据优先级：Netlify 不会覆盖你在项目或团队级设置的 key/base URL，若你自设 provider key 则网关让位；Gemini 在设置了 `GOOGLE_API_KEY` 或 `GOOGLE_VERTEX_BASE_URL` 时会跳过注入。
18. 要停止全部注入，可禁用 AI Features（见 Netlify 文档 manage-ai-features/#disable-ai-features）。
19. 计费与限制：仅限 credit-based 套餐（Free、Personal、Pro），Enterprise 联系客户经理，旧套餐需先切换；默认启用除非禁用 AI Features 或自设 provider key；$1 USD = 180 credits；速率限制（每团队每分钟、跨所有项目）Free 90、Personal 450、Pro 1,800、Enterprise 9,000 credits；输入上限 200k tokens；Anthropic 仅默认 5 分钟 ephemeral 缓存，OpenAI 按账号自动设 `prompt_cache_key`，Gemini 不支持显式上下文缓存；不支持透传 header、不支持 batch inference、不支持 OpenAI priority processing；OpenRouter 仅路由到有 Zero Data Retention 政策的 provider（可用模型见 https://openrouter.ai/models?zdr=true）；网关不存储 prompt 或模型输出。
20. 成本控制：给调用 AI 的 Functions/Edge Functions 设置限流规则防止访客滥用和费用失控，并配置自动充值或购买 credit packs；用 Netlify 的用量监控页面跟踪消耗。

适用边界 · 注意事项

• 非 Netlify 项目或未使用 Netlify Functions/Edge Functions 的场景。
• 需要在浏览器端直接调用模型、或在构建期/预渲染期生成 AI 内容的场景。
• 使用非 credit-based 旧套餐、Enterprise 未联系客户经理，或已禁用 AI Features 的团队。