RAG 架構實作:在 Cloudflare 上打造知識庫問答 | Cloudflare 完整教學

# ① 建立 768 維 cosine 索引(對應 @cf/baai/bge-base-en-v1.5)
npx wrangler vectorize create rag-index --dimensions=768 --metric=cosine

# ② 建立可過濾的 metadata index(要在寫入向量「之前」建好)
npx wrangler vectorize create-metadata-index rag-index --property-name=docId --type=string

# ③ 建立 D1 資料庫
npx wrangler d1 create rag-knowledge-base

npx wrangler d1 execute rag-knowledge-base --remote --command "
CREATE TABLE IF NOT EXISTS chunks (
  id TEXT PRIMARY KEY,       -- chunk ID,與 Vectorize 的向量 id 一致
  doc_id TEXT NOT NULL,      -- 所屬文件 ID
  content TEXT NOT NULL,     -- chunk 原文(餵給 LLM 的背景資訊)
  title TEXT NOT NULL,       -- 文件標題(用於標示來源)
  url TEXT
);
CREATE INDEX IF NOT EXISTS idx_doc_id ON chunks (doc_id);
"

// wrangler.jsonc
{
  "name": "rag-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "ai": { "binding": "AI" },
  "vectorize": [
    { "binding": "VECTORIZE", "index_name": "rag-index" }
  ],
  "d1_databases": [
    { "binding": "DB", "database_name": "rag-knowledge-base", "database_id": "你的-d1-database-id" }
  ]
}

// src/types.ts
export interface Env {
  AI: Ai;
  VECTORIZE: Vectorize;
  DB: D1Database;
}

export interface Document {
  id: string;
  title: string;
  content: string;
  url?: string;
}

// src/chunking.ts
// chunkSize:每段最大字元數;overlap:相鄰段落重疊字元數(避免語意被切點劈斷)
export function splitText(text: string, chunkSize = 800, overlap = 150): string[] {
  const chunks: string[] = [];
  let start = 0;

  while (start < text.length) {
    const end = Math.min(start + chunkSize, text.length);
    chunks.push(text.slice(start, end).trim());
    if (end === text.length) break;
    start = end - overlap; // ← 回退 overlap 個字元,讓下一段與這段頭尾重疊
  }

  return chunks.filter((c) => c.length > 0);
}

// src/indexing.ts
import type { Env, Document } from "./types";
import { splitText } from "./chunking";

export async function indexDocument(env: Env, doc: Document): Promise<{ chunks: number }> {
  // ① 分塊
  const chunkTexts = splitText(doc.content);

  // ② 批次產 embedding:一次把所有 chunk 傳給 Workers AI
  //    注意:index 與 query 必須用「同一個」模型 —— 這裡是 @cf/baai/bge-base-en-v1.5
  const embResult = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
    text: chunkTexts,
  });
  // embResult.data 是二維陣列,data[i] 對應 chunkTexts[i] 的 768 維向量

  const vectors: VectorizeVector[] = [];

  for (const [i, chunkText] of chunkTexts.entries()) {
    const chunkId = `${doc.id}-chunk-${i}`;

    // ③a 原文寫入 D1(之後檢索命中時用它撈回全文)
    await env.DB.prepare(
      "INSERT OR REPLACE INTO chunks (id, doc_id, content, title, url) VALUES (?, ?, ?, ?, ?)"
    )
      .bind(chunkId, doc.id, chunkText, doc.title, doc.url ?? null)
      .run();

    // ③b 準備向量:values 必須是 embResult.data[i](不是 embResult、也不是 embResult.data)
    vectors.push({
      id: chunkId,
      values: embResult.data[i],
      metadata: { docId: doc.id, title: doc.title },
    });
  }

  // ④ 批次 upsert 進 Vectorize(每批最多 1,000 個)
  const BATCH = 500;
  for (let i = 0; i < vectors.length; i += BATCH) {
    await env.VECTORIZE.upsert(vectors.slice(i, i + BATCH));
  }

  return { chunks: chunkTexts.length };
}

// src/rag.ts
import type { Env } from "./types";

export interface RAGResult {
  answer: string;
  sources: Array<{ title: string; url: string | null; score: number }>;
}

export async function ragQuery(
  env: Env,
  question: string,
  options: { topK?: number; scoreThreshold?: number } = {}
): Promise<RAGResult> {
  const { topK = 5, scoreThreshold = 0.5 } = options;

  // ① 問題向量化 —— 必須用與索引時「相同」的 embedding 模型!
  const emb = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [question] });
  const queryVector = emb.data[0];

  // ② 在 Vectorize 檢索最相似的 topK 個 chunk
  const matches = await env.VECTORIZE.query(queryVector, {
    topK,
    returnMetadata: "indexed",
  });

  // ③ 過濾低相似度結果:query 一定會回 topK 個,但不夠相關的要丟掉
  const relevant = matches.matches.filter((m) => m.score >= scoreThreshold);

  if (relevant.length === 0) {
    // 寧可誠實說「找不到」,也別硬塞不相關內容讓 LLM 幻覺
    return { answer: "抱歉,知識庫中找不到與您問題相關的資訊。", sources: [] };
  }

  // ④ 用 chunk ID 從 D1 撈回原文(Vectorize 只存向量,全文在 D1)
  const ids = relevant.map((m) => m.id);
  const placeholders = ids.map(() => "?").join(", ");
  const { results: chunks } = await env.DB.prepare(
    `SELECT id, content, title, url FROM chunks WHERE id IN (${placeholders})`
  )
    .bind(...ids)
    .all<{ id: string; content: string; title: string; url: string | null }>();

  // ⑤ 組 prompt:把檢索到的原文當成「背景資訊」—— 這就是 RAG 的「增強(Augmented)」
  const context = chunks
    .map((c, i) => `[來源 ${i + 1}:${c.title}]\n${c.content}`)
    .join("\n\n---\n\n");

  // ⑥ 呼叫 LLM 生成回答,明確要求「只根據背景資訊回答」
  const llm = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
    messages: [
      {
        role: "system",
        content: `你是一個嚴謹的知識助理。請「只根據」以下背景資訊,用繁體中文回答使用者的問題。
若背景資訊不足以回答,請如實說明「資料中沒有相關資訊」,絕對不要自行編造。

背景資訊:
${context}`,
      },
      { role: "user", content: question },
    ],
    max_tokens: 1024,
    temperature: 0.3, // 低溫度讓回答更貼近事實、少發散
  });

  // 整理來源(讓使用者能查證答案出處)
  const chunkMap = new Map(chunks.map((c) => [c.id, c]));
  const sources = relevant
    .map((m) => {
      const c = chunkMap.get(m.id);
      return c ? { title: c.title, url: c.url, score: m.score } : null;
    })
    .filter((s): s is NonNullable<typeof s> => s !== null);

  return { answer: llm.response ?? "無法生成回答", sources };
}

// src/index.ts
import { Hono } from "hono";
import type { Env } from "./types";
import { indexDocument } from "./indexing";
import { ragQuery } from "./rag";

const app = new Hono<{ Bindings: Env }>();

// 索引階段:POST 一份文件,系統自動分塊、產 embedding、雙寫入
app.post("/index", async (c) => {
  const doc = await c.req.json<{ id: string; title: string; content: string; url?: string }>();
  if (!doc.id || !doc.title || !doc.content) {
    return c.json({ error: "缺少必要欄位:id, title, content" }, 400);
  }
  const result = await indexDocument(c.env, doc);
  return c.json({ success: true, message: `文件 ${doc.id} 已索引`, ...result });
});

// 查詢階段:GET /ask?q=... 回傳 RAG 生成的答案 + 來源
app.get("/ask", async (c) => {
  const question = c.req.query("q");
  if (!question) return c.json({ error: "請提供問題參數 ?q=..." }, 400);

  const result = await ragQuery(c.env, question);
  return c.json(result);
});

export default app;

// ❌ 不過濾:把 topK 全部塞進 prompt,不相關的變雜訊
const relevant = matches.matches;

// ✅ 過濾:只留分數夠高的,寧可回「找不到」也別硬塞
const relevant = matches.matches.filter((m) => m.score >= 0.5);
if (relevant.length === 0) return { answer: "資料中沒有相關資訊。", sources: [] };