AI.run() 與常見任務:一個方法跑遍模型目錄 | Cloudflare 完整教學

async env.AI.run(
  model: string,   // 模型識別符,如 "@cf/meta/llama-3.1-8b-instruct"
  input: object,   // 「模型特定」的輸入物件 ← 各任務差在這
  options?: {      // 選用:執行期選項
    gateway?: { id: string; metadata?: Record<string, string | number | boolean | null> };
  }
): Promise<Response | ReadableStream>

export interface Env {
  AI: Ai;
}

// 【Chat 格式】用 system 定調 + user 提問(推薦)
async function chat(env: Env, question: string) {
  const result = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
    messages: [
      { role: "system", content: "你是一位專業技術顧問,只用繁體中文簡潔回答。" },
      { role: "user", content: question },
    ],
    temperature: 0.7, // 0–1,越高越有創意
    max_tokens: 512,  // 限制輸出長度(成本 + 延遲閘門)
  });
  return result.response; // 文字生成的答案在 result.response(字串)
}

// 【Completion 格式】單純字串補全
const result = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
  prompt: "用一句話解釋什麼是邊緣運算",
});
console.log(result.response);

// 讓模型穩定輸出 JSON:temperature=0 + system 約束
const result = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
  messages: [
    { role: "system", content: "你只輸出有效的 JSON 物件,不要有任何其他文字或說明。" },
    { role: "user", content: "提取重點:John 在台北的蘋果公司工作,月薪 10 萬。" },
  ],
  temperature: 0, // 關鍵:設 0 提高輸出一致性
});

try {
  const data = JSON.parse(result.response);
  console.log(data); // { name: "John", company: "蘋果", location: "台北", salary: 100000 }
} catch {
  console.error("JSON 解析失敗:", result.response);
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stream = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [{ role: "user", content: "寫一篇關於邊緣運算的短文" }],
      stream: true, // ← 回傳 ReadableStream,而非物件
    });

    // 直接把 stream 交給 Response,補上 SSE 專用標頭
    return new Response(stream as ReadableStream, {
      headers: {
        "Content-Type": "text/event-stream", // ← 必須!否則前端無法正確解析
        "Cache-Control": "no-cache",
        "Connection": "keep-alive",
      },
    });
  },
} satisfies ExportedHandler<Env>;

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stream = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [{ role: "user", content: "介紹三個 Cloudflare 產品" }],
      stream: true,
    });

    const { readable, writable } = new TransformStream();
    const writer = writable.getWriter();
    const encoder = new TextEncoder();

    // 非同步逐塊處理,不阻塞回應
    (async () => {
      for await (const chunk of stream as AsyncIterable<{ response?: string }>) {
        if (chunk.response) {
          await writer.write(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
        }
      }
      await writer.write(encoder.encode("data: [DONE]\n\n")); // 收尾訊號
      await writer.close();
    })();

    return new Response(readable, {
      headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
    });
  },
} satisfies ExportedHandler<Env>;

// 單筆:回傳一個 768 維向量
const single = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
  text: "What is machine learning?",
});
const vector = single.data[0]; // number[],長度 768

// 批次(推薦!):一次送多筆,更省 Neurons、更快
const batch = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
  text: [
    "Machine learning is a subset of AI",
    "Cloudflare Workers runs at the edge",
  ],
});
const [v1, v2] = batch.data; // data 是 number[][],順序對應輸入
console.log(`向量維度:${v1.length}`); // 768

export interface Env {
  AI: Ai;
  VECTORIZE: VectorizeIndex;
}

// 先建索引(注意 --dimensions 要對準模型維度):
// npx wrangler vectorize create kb --dimensions=768 --metric=cosine

async function ask(env: Env, question: string) {
  // 1. 問題轉 embedding
  const q = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: question });

  // 2. 向量搜尋 top-5 最相關文件
  const hits = await env.VECTORIZE.query(q.data[0], { topK: 5, returnMetadata: "all" });

  // 3. 過濾低相關度,組成上下文
  const context = hits.matches
    .filter((m) => m.score > 0.7)
    .map((m) => m.metadata?.text as string)
    .join("\n\n");

  // 4. 交給 LLM 依上下文作答
  const answer = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
    messages: [
      { role: "system", content: `請根據以下內容回答,找不到就如實說明。\n\n${context}` },
      { role: "user", content: question },
    ],
    max_tokens: 512,
  });
  return answer.response;
}

// 文字生成影像:回傳的是二進位圖片,不是物件
const image = await env.AI.run("@cf/black-forest-labs/flux-1-schnell", {
  prompt: "a cute robot coding at the edge of a network, isometric",
  num_steps: 20, // 步數(此模型上限約 20)
});

return new Response(image as ReadableStream, {
  headers: { "Content-Type": "image/png" }, // ← 用圖片 MIME,別回 JSON
});

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const form = await request.formData();
    const audioFile = form.get("audio") as File;

    // 音訊 → ArrayBuffer → 位元組陣列
    const bytes = Array.from(new Uint8Array(await audioFile.arrayBuffer()));

    const transcription = await env.AI.run("@cf/openai/whisper", { audio: bytes });

    // 逐字稿在 result.text(不是 .response!)
    return Response.json({ text: transcription.text });
  },
} satisfies ExportedHandler<Env>;

const tools = [
  {
    type: "function" as const,
    function: {
      name: "getWeather",
      description: "取得指定城市的即時天氣",
      parameters: {
        type: "object",
        properties: { city: { type: "string", description: "城市名稱,如:台北" } },
        required: ["city"],
      },
    },
  },
];

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const userMsg = "台北現在天氣怎麼樣?";

    // === 第一輪:模型決定「要不要」呼叫工具 ===
    const first = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [{ role: "user", content: userMsg }],
      tools,
    });

    // 沒有 tool_calls 就是直接回答了
    if (!first.tool_calls?.length) {
      return Response.json({ response: first.response });
    }

    // === 第二輪:實際執行工具,把結果餵回模型 ===
    const call = first.tool_calls[0];
    const args = JSON.parse(call.function.arguments);
    const weather = await fetchWeather(args.city); // 你真正的實作

    const final = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [
        { role: "user", content: userMsg },
        { role: "assistant", content: JSON.stringify(first.tool_calls) },
        { role: "tool", content: JSON.stringify(weather) },
      ],
      tools,
    });

    return Response.json({ response: final.response });
  },
} satisfies ExportedHandler<Env>;

async function fetchWeather(city: string) {
  return { city, temperature: 28, condition: "晴天" }; // 模擬 API
}

// ❌ 不設上限,可能生成過長
await env.AI.run(model, { messages });

// ✅ 依場景設 max_tokens(摘要 512、簡短回覆 256…)
await env.AI.run(model, { messages, max_tokens: 512 });

// ❌ 對串流結果讀 .response → undefined
const s = await env.AI.run(model, { messages, stream: true });
return Response.json({ answer: s.response });

// ✅ 直接把 stream 放進 Response,帶正確 SSE 標頭
return new Response(s as ReadableStream, {
  headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
});

# ✅ bge-base-en-v1.5 是 768 維,索引就建 768 維
npx wrangler vectorize create kb --dimensions=768 --metric=cosine

// ❌ 逐筆:慢又貴
for (const t of texts) await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: t });

// ✅ 批次:一次送完
const res = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: texts });