> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# RAG 系統中的檢索

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

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

## 檢索的運作方式

1. 使用文件嵌入所用的相同模型，將使用者查詢轉換成嵌入向量
2. 使用向量相似度，將此嵌入向量與已儲存的嵌入向量進行比較
3. 檢索最相似的片段，並可選擇進行下列處理：

- 依 metadata 篩選
- 重新排序以提高相關性
- 透過知識圖譜處理

## 基本檢索

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

```ts
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` 參數指定向量搜尋最多傳回幾筆最相似的結果。

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

```ts
[
  {
    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 篩選器的方式，有時稱為混合向量搜尋，因為它融合了語意搜尋與結構化篩選條件。

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

如需可用運算子與語法的詳細資訊，請參閱 [Metadata 篩選器參考文件](https://mastra.zisheng.pro/zh-TW/reference/rag/metadata-filters)。

基本篩選範例：

```ts
// 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

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

```ts
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: '...' })`）。

```ts
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，在執行階段覆寫這些設定：

```ts
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 參考文件](https://mastra.zisheng.pro/zh-TW/reference/tools/vector-query-tool)。

### 向量儲存 prompt

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

**pgVector**:

```ts
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 },
})
```

**Pinecone**:

```ts
import { PINECONE_PROMPT } from '@mastra/pinecone'

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.
  ${PINECONE_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**Qdrant**:

```ts
import { QDRANT_PROMPT } from '@mastra/qdrant'

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.
  ${QDRANT_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**Chroma**:

```ts
import { CHROMA_PROMPT } from '@mastra/chroma'

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.
  ${CHROMA_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**Astra**:

```ts
import { ASTRA_PROMPT } from '@mastra/astra'

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.
  ${ASTRA_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**libSQL**:

```ts
import { LIBSQL_PROMPT } from '@mastra/libsql'

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.
  ${LIBSQL_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**Upstash**:

```ts
import { UPSTASH_PROMPT } from '@mastra/upstash'

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.
  ${UPSTASH_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**Vectorize**:

```ts
import { VECTORIZE_PROMPT } from '@mastra/vectorize'

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.
  ${VECTORIZE_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**MongoDB**:

```ts
import { MONGODB_PROMPT } from '@mastra/mongodb'

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.
  ${MONGODB_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**OpenSearch**:

```ts
import { OPENSEARCH_PROMPT } from '@mastra/opensearch'

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.
  ${OPENSEARCH_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**OracleDB**:

```ts
import { ORACLEDB_PROMPT } from '@mastra/oracledb'

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.
  ${ORACLEDB_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

**S3Vectors**:

```ts
import { S3VECTORS_PROMPT } from '@mastra/s3vectors'

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.
  ${S3VECTORS_PROMPT}
  `,
  tools: { vectorQueryTool },
})
```

### 重新排序

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

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

重新排序的用法如下：

```ts
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：

```ts
const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
```

```ts
const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1')
```

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

如需重新排序的詳細資訊，請參閱 [rerank()](https://mastra.zisheng.pro/zh-TW/reference/rag/rerankWithScorer) 方法。

若要依片段間連結進行圖形檢索，請參閱 [GraphRAG](https://mastra.zisheng.pro/zh-TW/guides/rag/graph-rag) 文件。