跳至主要內容

RAG 系統中的檢索

儲存嵌入向量後，你需要檢索相關片段來回答使用者查詢。

Mastra 提供彈性的檢索選項，支援語意搜尋、篩選及重新排序。

檢索的運作方式
「檢索的運作方式」的直接連結

  1. 使用文件嵌入所用的相同模型，將使用者查詢轉換成嵌入向量
  2. 使用向量相似度，將此嵌入向量與已儲存的嵌入向量進行比較
  3. 檢索最相似的片段，並可選擇進行下列處理：
  • 依 metadata 篩選
  • 重新排序以提高相關性
  • 透過知識圖譜處理

基本檢索
「基本檢索」的直接連結

最簡單的方式是直接進行語意搜尋。此方法使用向量相似度找出與查詢語意相似的片段：

import { embed } from 'ai'
import { PgVector } from '@mastra/pg'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

// Convert query to embedding
const { embedding } = await embed({
  value: 'What are the main points in the article?',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})

// Query vector store
const pgVector = new PgVector({
  id: 'pg-vector',
  connectionString: process.env.POSTGRES_CONNECTION_STRING,
})
const results = await pgVector.query({
  indexName: 'embeddings',
  queryVector: embedding,
  topK: 10,
})

// Display results
console.log(results)

topK 參數指定向量搜尋最多傳回幾筆最相似的結果。

結果同時包含文字內容與相似度分數：

[
  {
    text: 'Climate change poses significant challenges...',
    score: 0.89,
    metadata: { source: 'article1.txt' },
  },
  {
    text: 'Rising temperatures affect crop yields...',
    score: 0.82,
    metadata: { source: 'article1.txt' },
  },
]

進階檢索選項
「進階檢索選項」的直接連結

Metadata 篩選
「Metadata 篩選」的直接連結

根據 metadata 欄位篩選結果，可縮小搜尋範圍。這種結合向量相似度搜尋與 metadata 篩選器的方式，有時稱為混合向量搜尋，因為它融合了語意搜尋與結構化篩選條件。

當文件來自不同來源、時間範圍，或具有特定屬性時，此功能十分實用。Mastra 提供統一的 MongoDB 風格查詢語法，可在所有支援的向量儲存中使用。

如需可用運算子與語法的詳細資訊，請參閱 Metadata 篩選器參考文件。

基本篩選範例：

// Simple equality filter
const results = await pgVector.query({
  indexName: 'embeddings',
  queryVector: embedding,
  topK: 10,
  filter: {
    source: 'article1.txt',
  },
})

// Numeric comparison
const results = await pgVector.query({
  indexName: 'embeddings',
  queryVector: embedding,
  topK: 10,
  filter: {
    price: { $gt: 100 },
  },
})

// Multiple conditions
const results = await pgVector.query({
  indexName: 'embeddings',
  queryVector: embedding,
  topK: 10,
  filter: {
    category: 'electronics',
    price: { $lt: 1000 },
    inStock: true,
  },
})

// Array operations
const results = await pgVector.query({
  indexName: 'embeddings',
  queryVector: embedding,
  topK: 10,
  filter: {
    tags: { $in: ['sale', 'new'] },
  },
})

// Logical operators
const results = await pgVector.query({
  indexName: 'embeddings',
  queryVector: embedding,
  topK: 10,
  filter: {
    $or: [{ category: 'electronics' }, { category: 'accessories' }],
    $and: [{ price: { $gt: 50 } }, { price: { $lt: 200 } }],
  },
})

Metadata 篩選的常見使用情境：

  • 依文件來源或類型篩選
  • 依日期範圍篩選
  • 依特定類別或標籤篩選
  • 依數值範圍篩選（例如價格、評分）
  • 結合多個條件以進行精確查詢
  • 依文件屬性篩選（例如語言、作者）

Vector Query Tool
「Vector Query Tool」的直接連結

有時你會希望 Agent 能直接查詢向量資料庫。Vector Query Tool 讓 Agent 負責決定如何檢索，並依 Agent 對使用者需求的理解，結合語意搜尋、選用的篩選及重新排序。

import { createVectorQueryTool } from '@mastra/rag'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

const vectorQueryTool = createVectorQueryTool({
  vectorStoreName: 'pgVector',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})

建立 Tool 時，請特別留意 Tool 的名稱與說明，這些資訊可協助 Agent 理解何時及如何使用檢索功能。例如，你可以將它命名為「SearchKnowledgeBase」，並說明為「搜尋文件以尋找 X 主題的相關資訊」。

此功能特別適合以下情境：

  • Agent 需要在執行階段決定要檢索哪些資訊
  • 檢索流程需要複雜的決策
  • 你希望 Agent 根據脈絡結合多種檢索策略

資料庫特有設定
「資料庫特有設定」的直接連結

Vector Query Tool 支援資料庫特有設定，讓你使用不同向量儲存的獨特功能與最佳化選項。

備註

這些設定用於 namespace、效能調校及篩選等查詢階段選項，而非設定資料庫連線。

連線憑證（URL、驗證 token）會在建立向量儲存類別的執行個體時設定（例如 new LibSQLVector({ url: '...' })）。

import { createVectorQueryTool } from '@mastra/rag'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

// Pinecone with namespace
const pineconeQueryTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    pinecone: {
      namespace: 'production', // Isolate data by environment
    },
  },
})

// pgVector with performance tuning
const pgVectorQueryTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    pgvector: {
      minScore: 0.7, // Filter low-quality results
      ef: 200, // HNSW search parameter
      probes: 10, // IVFFlat probe parameter
    },
  },
})

// Chroma with advanced filtering
const chromaQueryTool = createVectorQueryTool({
  vectorStoreName: 'chroma',
  indexName: 'documents',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    chroma: {
      where: { category: 'technical' },
      whereDocument: { $contains: 'API' },
    },
  },
})

// LanceDB with table specificity
const lanceQueryTool = createVectorQueryTool({
  vectorStoreName: 'lance',
  indexName: 'documents',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    lance: {
      tableName: 'myVectors', // Specify which table to query
      includeAllColumns: true, // Include all metadata columns in results
    },
  },
})

主要優點：

  • Pinecone namespace：依租戶、環境或資料類型整理向量
  • pgVector 最佳化：透過 ef/probes 參數控制搜尋準確度與速度
  • 品質篩選：設定最低相似度閾值，以提高結果相關性
  • LanceDB 資料表：將資料分隔至不同資料表，以改善整理方式與效能
  • 執行階段彈性：根據脈絡在執行階段覆寫設定

常見使用情境：

  • 使用 Pinecone namespace 的多租戶應用程式
  • 高負載情境中的效能最佳化
  • 環境特有設定（dev/staging/prod）
  • 設有品質門檻的搜尋結果
  • 在邊緣部署情境中使用 LanceDB 的嵌入式檔案型向量儲存

你也可以使用 request context，在執行階段覆寫這些設定：

import { RequestContext } from '@mastra/core/request-context'

const requestContext = new RequestContext()
requestContext.set('databaseConfig', {
  pinecone: {
    namespace: 'runtime-namespace',
  },
})

await pineconeQueryTool.execute({ queryText: 'search query' }, { mastra, requestContext })

如需詳細設定選項與進階用法，請參閱 Vector Query Tool 參考文件。

向量儲存 prompt
「向量儲存 prompt」的直接連結

向量儲存 prompt 會為各種向量資料庫實作定義查詢模式與篩選功能。 實作篩選時，Agent 的 instructions 必須包含這些 prompt，才能指定各向量儲存實作的有效運算子與語法。

import { PGVECTOR_PROMPT } from '@mastra/pg'

export const ragAgent = new Agent({
  id: 'rag-agent',
  name: 'RAG Agent',
  model: 'openai/gpt-5.6-sol',
  instructions: `
  Process queries using the provided context. Structure responses to be concise and relevant.
  ${PGVECTOR_PROMPT}
  `,
  tools: { vectorQueryTool },
})

重新排序
「重新排序」的直接連結

初始向量相似度搜尋有時會遺漏細微的相關性。重新排序需要較多運算資源，但演算法更準確，可透過以下方式改善結果：

  • 考量詞序與完全相符項目
  • 套用更進階的相關性評分
  • 在查詢與文件之間使用稱為 cross-attention 的方法

重新排序的用法如下：

import { rerankWithScorer as rerank, MastraAgentRelevanceScorer } from '@mastra/rag'

// Get initial results from vector search
const initialResults = await pgVector.query({
  indexName: 'embeddings',
  queryVector: queryEmbedding,
  topK: 10,
})

// Create a relevance scorer
const relevanceProvider = new MastraAgentRelevanceScorer(
  'relevance-scorer',
  'openai/gpt-5.6-sol',
)

// Re-rank the results
const rerankedResults = await rerank({
  results: initialResults,
  query,
  scorer: relevanceProvider,
  options: {
    weights: {
      semantic: 0.5, // How well the content matches the query semantically
      vector: 0.3, // Original vector similarity score
      position: 0.2, // Preserves original result ordering
    },
    topK: 10,
  },
})

權重會控制不同因素對最終排序的影響：

  • semantic：值越高，越優先考量語意理解及與查詢的相關性
  • vector：值越高，越偏重原始向量相似度分數
  • position：值越高，越有助於維持原始結果順序
備註

若要讓語意評分在重新排序期間正常運作，每筆結果的 metadata.text 欄位都必須包含文字內容。

你也可以使用 Cohere 或 ZeroEntropy 等其他相關性評分 Provider：

const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1')

重新排序後的結果會結合向量相似度與語意理解，以提高檢索品質。

如需重新排序的詳細資訊，請參閱 rerank() 方法。

若要依片段間連結進行圖形檢索，請參閱 GraphRAG 文件。

On this page