跳至主要内容

RAG 知識庫

RAG（Retrieval-Augmented Generation，檢索增強生成）讓 AI 根據你提供的文件回答問題，而不是憑空生成可能不正確的答案。

簡單說：上傳你的文件 → AI 根據這些文件回答問題 → 每個回答都附帶來源引用。

運作原理​

你的問題 → 語義搜尋知識庫 → 找到最相關的文件段落
         → 把這些段落連同問題一起送給 AI
         → AI 根據文件內容生成有依據的回答
         → 回傳答案 + 引用的文件來源

快速上手​

步驟 1：上傳文件​

在 Dashboard 新增專案後，上傳你的文件。支援的格式：

  • PDF
  • Markdown (.md)
  • Word (.docx)
  • 純文字 (.txt)
  • HTML

上傳後系統會自動處理（解析 → 切分 → 向量化），通常幾分鐘內完成。

你也可以用 API 上傳：

import { readFile } from 'node:fs/promises';

const buffer = await readFile('./product-manual.pdf');

const doc = await client.documents.upload({
  file: buffer,
  filename: 'product-manual.pdf',
  contentType: 'application/pdf',
});

console.log('上傳成功，文件 ID:', doc.id);
console.log('狀態:', doc.status); // processing → ready

步驟 2：用 AI 查詢知識庫​

文件處理完成後，在 Chat 請求中開啟 rag: true：

const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Docker 和 虚擬機的差異是什麼？什麼場景適合用哪個？' }],
  vecstruct: {
    rag: true,
    rag_top_k: 5,       // 參考最相關的 5 個段落
  },
});

console.log(reply.choices[0].message.content);

// 查看引用了哪些段落
for (const src of reply.vecstruct?.rag_sources ?? []) {
  console.log(`來源: ${src.title} (相似度: ${src.similarity.toFixed(2)})`);
  console.log(`  段落: ${src.chunk.slice(0, 100)}...`);
}

步驟 3：直接查詢知識庫（不生成回覆）​

如果你只需要查找相關文件段落，不需要 AI 生成回覆，用 RAG Query API：

const result = await client.rag.query({
  query: 'Kubernetes pod 排除故障步驟',
  config: {
    top_k: 5,
    min_similarity: 0.7,
  },
});

for (const r of result.results) {
  console.log(`相似度: ${r.score.toFixed(3)}`);
  console.log(`內容: ${r.content.slice(0, 200)}`);
  console.log(`來源文件: ${r.source?.name}`);
}

應用場景範例​

範例一：個人技術知識庫​

把你的技術筆記、讀過的文章、整理的資料上傳到知識庫。之後可以直接問 AI，不用自己翻。

// 查詢你幾個月前整理的筆記
const result = await client.rag.query({
  query: 'React useEffect 清除訂閱的寫法',
  config: { top_k: 5 },
});

常見情境： 開發者的技術文件、個人學習筆記、Obsidian vault、讀書筆記

範例二：開發團隊內部知識庫​

把 Runbook、Incident Report、ADR（架構決策記錄）、API 文件上傳之後，新成員上手不用再一直問人。

const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '我們的 PostgreSQL 要怎麼做備份？上次 OOM 故障是怎麼解決的？' }],
  vecstruct: { rag: true },
});

常見情境： 技術團隊的 SOP、故障處理紀錄、開發規範、CI/CD 文件

範例三：研究資料整理​

上傳論文、研究報告、改進文獻，AI 幫你跨文件查找和整理重點。

const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '這些論文裡有哪些提到 attention mechanism 的改進方向？幫我整理重點。' }],
  vecstruct: { rag: true, rag_top_k: 10 },
});

常見情境： 學術研究、競爭分析、市場研究報告、產業報告整理

範例四：在自己的產品裡嵌入 AI 文件查詢​

在你的 SaaS 中嵌入 AI 問答功能，讓用戶可以直接查詢你的產品文件、常見問題。

const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'system', content: '你是 Acme App 的助理，根據產品文件回答問題。超出文件範圍的問題請直接說不知道。' },
    { role: 'user', content: '我要怎麼設定 webhook？' },
  ],
  vecstruct: { rag: true, rag_top_k: 5 },
});

常見情境： SaaS 產品內嵌式助手、開源專案文件查詢、課程教材問答

控制 RAG 行為​

rag_top_k：回傳幾個段落​

預設使用專案設定，可在請求中覆蓋。值越大，AI 參考的資訊越多，但回答越長且費用略高。

vecstruct: {
  rag: true,
  rag_top_k: 3,   // 只取最相關的 3 個段落
}

指定特定文件​

如果只想讓 AI 參考特定幾份文件：

vecstruct: {
  rag: true,
  // 只從這些文件 ID 裡搜尋
  // 文件 ID 可從 Documents API 取得
}

在 RAG Query API 中用 source_ids 限定：

const result = await client.rag.query({
  query: 'API 排除錯誤方法',
  source_ids: ['doc-id-1', 'doc-id-2'],  // 只搜尋這兩份文件
});

關閉 RAG​

如果 API Key 綁定了專案，預設會開啟 RAG。在某些對話不需要知識庫時可以關閉：

vecstruct: {
  rag: false,  // 這個請求不查詢知識庫
}

注意事項​

  • 文件上傳後需要等待處理完成（狀態變為 ready）才能查詢
  • 查詢結果的品質取決於文件內容的清晰度和完整性
  • PDF 會透過 OCR 識別技術轉換為文字，圖片中的文字也能辨識
  • 每次 RAG 查詢會消耗 Credits（費用詳見 Pricing）