架構藍圖：AI 問答應用（RAG）

我們要做一個會根據你自己文件回答問題的問答應用。單純的大型語言模型（LLM）只懂得它訓練時看過的東西，所以無法回答你私有手冊裡的內容——而且還可能很有自信地亂編。RAG（Retrieval-Augmented Generation，檢索增強生成）就是來解決這個問題：先「檢索」出文件中最相關的片段，再讓 LLM 只根據這些片段「生成」答案。

RAG 有兩個階段。離線的「匯入」階段會讀進你的文件，把它們變成向量（一串能代表語意的數字）並存起來。線上的「查詢」階段則接收使用者的問題，找出最相近的片段，再把它們當成上下文（context）餵給 LLM。整體長這樣：

五個 Cloudflare 元件分工合作。Worker 是指揮；Workers AI 提供大腦（負責向量化與 LLM）；Vectorize 是可搜尋的記憶；D1 保存原始可讀的文字；R2 則存放原始檔案。

匯入對每份文件只需跑一次（或在它更新時跑）。我們把文件切成小片段（chunk），用 Workers AI 把每段向量化，再把向量存進 Vectorize、把原始文字存進 D1。靠 id 把兩邊綁在一起：同一個 id 同時存在於兩個儲存層。

查詢時，我們用「和匯入時相同」的模型把問題向量化，到 Vectorize 搜尋最接近的前 k 個片段，從 D1 撈回它們的原始文字，再拼成一段 prompt。LLM 讀完這段上下文加上問題後，寫出有依據的答案。

當使用者問一個問題時，Worker 內部到底發生什麼事——Workers AI、Vectorize 和 D1 之間的每一次往返都在這裡：

以下是一個完整、可執行的 Worker，包含兩條路由：POST /ingest 用來把文件建索引，POST /ask 用來回答問題。先建立資源、定義資料表、接好繫結（binding），再加上程式碼。

1. 建立索引與資料庫

   索引維度（768）必須對應下面的 embedding 模型。bge 系列模型建議用 cosine（餘弦）距離。

   bashcontent_copy複製

   # Index sized for the bge-base embedding model (768 dims)
   wrangler vectorize create rag-index --dimensions=768 --metric=cosine
   
   # A D1 database to keep each chunk's original text
   wrangler d1 create rag-db

2. 建立 chunks 資料表

   存成 schema.sql，再執行：wrangler d1 execute rag-db --remote --file=./schema.sql

   sqlcontent_copy複製

   CREATE TABLE IF NOT EXISTS chunks (
     id      TEXT PRIMARY KEY,
     doc_id  TEXT,
     text    TEXT NOT NULL
   );

3. 接好繫結

   繫結讓程式能用 env.AI、env.VECTORIZE、env.DB 來存取 AI、Vectorize 與 D1——原始碼裡不必放金鑰。把 database_id 換成『wrangler d1 create』印出來的那組 id。

   jsonccontent_copy複製

   {
     "name": "rag-worker",
     "main": "src/index.js",
     "compatibility_date": "2025-06-01",
     "ai": { "binding": "AI" },
     "vectorize": [
       { "binding": "VECTORIZE", "index_name": "rag-index" }
     ],
     "d1_databases": [
       { "binding": "DB", "database_name": "rag-db", "database_id": "<your-d1-id>" }
     ]
   }

4. 匯入：切段、向量化、儲存

   一次 env.AI.run() 就把所有片段一起向量化。我們用 upsert 把向量寫進 Vectorize（具冪等性，重新匯入同一份文件也安全），並用 INSERT OR REPLACE 以相同 id 把文字寫進 D1。

   jscontent_copy複製

   // POST /ingest  { docId, text }
   async function ingest(env, docId, fullText) {
     // 1) Split the document into small overlapping chunks
     const chunks = chunkText(fullText, 200, 40);
   
     // 2) Embed every chunk in one Workers AI call
     const { data } = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
       text: chunks,
     });
   
     // 3) Save original text in D1, vectors in Vectorize
     const vectors = [];
     for (let i = 0; i < chunks.length; i++) {
       const id = docId + ":" + i;
       await env.DB.prepare(
         "INSERT OR REPLACE INTO chunks (id, doc_id, text) VALUES (?, ?, ?)"
       ).bind(id, docId, chunks[i]).run();
       vectors.push({ id, values: data[i], metadata: { docId } });
     }
     await env.VECTORIZE.upsert(vectors);
     return chunks.length;
   }
   
   // Split text into word chunks with a little overlap for context
   function chunkText(text, size, overlap) {
     const words = text.split(/\s+/);
     const out = [];
     for (let i = 0; i < words.length; i += size - overlap) {
       out.push(words.slice(i, i + size).join(" "));
     }
     return out;
   }

5. 提問：向量化、檢索、生成

   這是 RAG 的核心。把問題向量化，用 query() 向 Vectorize 取前 5 名，從 D1 撈回這些片段的文字，當成上下文交給 LLM。系統提示（system prompt）強制模型只能根據這段上下文作答。

   jscontent_copy複製

   // POST /ask  { question }
   async function ask(env, question) {
     // 1) Embed the question with the SAME model used at ingest
     const { data } = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
       text: [question],
     });
     const queryVector = data[0];
   
     // 2) Retrieve the top-k most similar chunks from Vectorize
     const { matches } = await env.VECTORIZE.query(queryVector, {
       topK: 5,
       returnMetadata: true,
     });
   
     // 3) Load the original text of those chunks from D1
     const ids = matches.map((m) => m.id);
     const slots = ids.map(() => "?").join(", ");
     const { results } = await env.DB.prepare(
       "SELECT text FROM chunks WHERE id IN (" + slots + ")"
     ).bind(...ids).all();
     const context = results.map((r) => r.text).join("\n---\n");
   
     // 4) Generate an answer grounded ONLY in that context
     const out = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
       messages: [
         {
           role: "system",
           content:
             "Answer using ONLY the context below. If it is not there, say you do not know.",
         },
         {
           role: "user",
           content: "Context:\n" + context + "\n\nQuestion: " + question,
         },
       ],
     });
     return out.response;
   }

6. 把請求接到路由

   default export 把 POST /ingest 與 POST /ask 派發給上面兩個函式，並回傳 JSON。

   jscontent_copy複製

   export default {
     async fetch(request, env) {
       const url = new URL(request.url);
   
       if (request.method === "POST" && url.pathname === "/ingest") {
         const { docId, text } = await request.json();
         const count = await ingest(env, docId, text);
         return Response.json({ ingested: count });
       }
   
       if (request.method === "POST" && url.pathname === "/ask") {
         const { question } = await request.json();
         const answer = await ask(env, question);
         return Response.json({ answer });
       }
   
       return new Response("POST JSON to /ingest or /ask", { status: 404 });
     },
   };

7. 部署並試用

   部署、匯入一份文件，再針對它提問。答案應該引用你的文件，而不是模型的訓練資料。

   bashcontent_copy複製

   wrangler deploy
   
   # Index a document
   curl -X POST https://rag-worker.example.workers.dev/ingest \
     -d '{ "docId": "handbook", "text": "Refunds are accepted within 30 days..." }'
   
   # Ask a question about it
   curl -X POST https://rag-worker.example.workers.dev/ask \
     -d '{ "question": "How long do I have to get a refund?" }'

• 維度必須一致：索引維度、embedding 模型、你 upsert 的向量三者都要對得上（這裡是 768）。
• 問題一定要用「和文件相同」的模型來向量化——不一致會悄悄回傳不相關的結果。
• Vectorize 存的是數字、不是文字。可讀文字放 D1（小片段）或 R2（整份檔案），再用 id 對接。
• 調整片段大小與 top-k：片段越小越精準，top-k 越大越完整但更花錢、也可能撐爆上下文視窗。
• 在 Workers AI 前面加上 AI Gateway，可對 embedding 與 LLM 兩種呼叫做快取、限流與觀測。
• 文件更新時要重新匯入；用固定的 id 做 upsert，舊向量會被取代而不是重複堆積。