Model API：讓產品第一次真的呼叫模型

先把 AI 功能畫成一般 Web App 資料流

模型不是魔法元件。它只是你的 backend 會呼叫的另一個外部服務。

最重要的是：Frontend 不直接持有模型 provider 的 secret API key。

為什麼不能直接從 browser 呼叫模型 API？

只要 secret 被放進送到瀏覽器的 JavaScript，使用者就能在 source、bundle 或 Network panel 找到它。

// 不要放在 frontend
const apiKey = "sk-...";

正確邊界：

這和 Web App Lesson 05 的 secret 原則完全一樣。

先把 provider-specific code 限制在一小塊

AI Builder 會用 OpenAI Responses API 當一個具體例子，但你的產品邏輯不要寫成「整個 app 都依賴某一個 SDK object」。

先想成一個 function：

generateText({ input })
  → 回傳字串

之後換模型、換 provider、加 routing，都只需要改 adapter，而不是整個產品。

先準備 server-side environment

本機可以在不 commit 的 .dev.vars 或 .env 放：

OPENAI_API_KEY=replace-me
OPENAI_MODEL=replace-with-a-current-model-id

不要把 model ID 永久散落在十個檔案。用 environment 或集中設定，之後才能比較模型、切換成本與能力。

安裝官方 JavaScript SDK

npm install openai

在 server-side / Worker code：

import OpenAI from "openai";

function createModelClient(env) {
  return new OpenAI({
    apiKey: env.OPENAI_API_KEY
  });
}

API key 由 runtime environment 注入，不出現在 frontend，也不 commit 進 Git。

第一次 model call：只有一個 input

async function generateText(env, input) {
  const client = createModelClient(env);

  const response = await client.responses.create({
    model: env.OPENAI_MODEL,
    input
  });

  return response.output_text;
}

目前 OpenAI 的 Responses API 可以用 input 建立模型回應；官方 SDK 也提供 output_text 這個方便欄位，避免你假設 output array 第一項一定是文字訊息。

OpenAI Responses API reference

Model call 不是你的 route 本身

Route 還是要做 Web App 已經學過的工作：

例如：

async function handleAsk(request, env) {
  const body = await request.json();

  if (
    !body ||
    typeof body.prompt !== "string" ||
    body.prompt.trim() === ""
  ) {
    return Response.json(
      {
        error: {
          code: "INVALID_INPUT",
          message: "prompt is required"
        }
      },
      { status: 400 }
    );
  }

  const prompt = body.prompt.trim();

  if (prompt.length > 4000) {
    return Response.json(
      {
        error: {
          code: "INPUT_TOO_LONG",
          message: "prompt is too long"
        }
      },
      { status: 400 }
    );
  }

  try {
    const text = await generateText(env, prompt);

    return Response.json({ text });
  } catch (error) {
    console.error("model request failed", error);

    return Response.json(
      {
        error: {
          code: "MODEL_ERROR",
          message: "Model request failed"
        }
      },
      { status: 502 }
    );
  }
}

Provider 的完整 internal error 不需要原封不動送給使用者。

把它接成 POST /api/ask

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    if (
      request.method === "POST" &&
      url.pathname === "/api/ask"
    ) {
      return handleAsk(request, env);
    }

    return new Response("Not found", {
      status: 404
    });
  }
};

現在你的 AI backend 和前面的 CRUD API 沒有本質上的魔法差異：仍然是 request、validation、business logic、external dependency、response。

Frontend 只知道你自己的 API

const response = await fetch("/api/ask", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: promptInput.value
  })
});

成功後：

const data = await response.json();
result.textContent = data.text;

Frontend 不需要知道 provider API key，甚至不一定要知道 backend 最後選的是哪個 model。

模型輸出不是「資料庫真相」

這堂課最重要的觀念之一：

模型可能：

所以不要因為 API 回 200 就把 output 當成已驗證事實。後面的 Structured Output、RAG、Tool Calling 都是在處理這個問題。

Latency：模型 call 通常比一般 database query 慢

Frontend 不應該在按下按鈕後像什麼都沒發生。

至少要有：

例如：

askButton.disabled = true;
status.textContent = "Thinking...";

完成或失敗後再恢復。

模型 latency 是產品體驗的一部分，不是「之後再優化」才需要知道。

不要讓使用者連點製造一堆昂貴 request

最小版本至少可以：

真正 production 還要考慮 per-user quota、abuse detection、provider limits 與預算。

Usage：AI request 不是免費抽象函式

模型 API 通常會產生可計量 usage。不要只記「成功 / 失敗」，還要建立成本意識。

可以在 server log 或 usage table 記錄非敏感 metadata，例如：

但不要把使用者完整 prompt、secret、session token 無腦全部塞進 log。

Provider error 和你的產品 error 要分開

可能失敗的地方很多：

Frontend 最好只依賴你自己的穩定 error schema，不要把某個 provider 的原始 response shape 當成產品 API contract。

先做最小 timeout 心理模型

任何 external API 都可能卡住。你的 backend 應該知道「等多久算失敗」。

實作方式依 runtime / SDK 而異，但架構上要有：

不要讓一個 client request 無限制佔著資源。

不要把 prompt 和 instructions 混成一大坨

這一課先只傳 input，下一課會正式拆：

例如「你是一個學習助教」這類產品規則，不應該每次都假裝是使用者自己輸入的內容。

小挑戰：做一個 AI Explain 按鈕

不要先做聊天紀錄。做一個單次任務就好：

用 DevTools Network 重新看一次資料流

Browser 應該只看得到：

POST /api/ask

它不應該拿到你的 provider API key。

Server-side 才負責：

最後收斂：AI 功能首先還是一個系統功能

如果這條線都還不穩，先不要急著加記憶、RAG、Agent 或十個 tools。

下一課會處理最常被低估的一層：Prompt / Instructions。你會把「產品規則」和「使用者輸入」拆開，開始真正控制模型任務。