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

# 搜尋及索引

**新增於：** `@mastra/core@1.1.0`

搜尋功能讓 Agent 在已建立索引的 Workspace 文件中尋找相關內容。當 Agent 需要回答問題或尋找資料時，可以搜尋已建立索引的內容，毋須讀取每個文件。

## 運作方式

Workspace 搜尋分為兩個階段：建立索引及查詢。

### 建立索引

內容必須先建立索引，才能供搜尋。為文件建立索引時：

- 內容會被斷詞（拆分成可搜尋的詞彙）
- 對於 BM25：系統會計算詞頻及文件統計資料
- 對於向量搜尋：系統會使用你的 embedder 函式將內容嵌入，並儲存至向量儲存空間

每份已建立索引的文件均包含：

- **id** - 唯一識別碼（通常是文件路徑）
- **content** - 文字內容
- **metadata** - 與文件一併儲存的可選鍵值資料

### 查詢

搜尋時：

1. 查詢會使用與建立索引時相同的斷詞／嵌入方式處理
2. 系統會根據文件與查詢的相關程度評分
3. 結果會按分數排序，並連同相符內容傳回

Workspace 支援三種搜尋模式：BM25 關鍵字搜尋、向量語義搜尋，以及結合兩者的混合搜尋。

## BM25 關鍵字搜尋

BM25 根據詞頻及文件長度為文件評分，適合用於完全相符及特定術語搜尋。

```typescript
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  bm25: true,
})
```

如要自訂 BM25 參數（`k1` 是詞頻飽和度，`b` 是文件長度正規化參數）：

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  bm25: {
    k1: 1.5,
    b: 0.75,
  },
})
```

## 向量搜尋

向量搜尋使用嵌入向量尋找語義相近的內容。此功能需要向量儲存空間及 embedder 函式。

```typescript
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { PineconeVector } from '@mastra/pinecone'
import { embed } from 'ai'
import { openai } from '@ai-sdk/openai'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  vectorStore: new PineconeVector({
    apiKey: process.env.PINECONE_API_KEY,
    index: 'workspace-index',
  }),
  embedder: async (text: string) => {
    const { embedding } = await embed({
      model: openai.embedding('text-embedding-3-small'),
      value: text,
    })
    return embedding
  },
})
```

### 批次嵌入

上面的 embedder 每次處理一段文字。為包含數百個文件的 Workspace 建立索引時，會呼叫 Provider 數百次，既緩慢又昂貴。

如果 Provider 支援批次處理（例如 OpenAI 的 `embedMany`），請傳入一個接受文字陣列，並可在一次呼叫中接收多個嵌入向量的 embedder。如要啟用此功能，請在函式上設定 `batch: true` 屬性。Mastra 會在執行階段檢查該屬性，並切換至批次處理路徑。

以下範例以批次 embedder 取代單一文字 embedder。embedder 函式接受一個陣列，並按相同順序傳回嵌入向量陣列，另附有兩個額外屬性：

- `batch: true`：將函式標記為支援批次處理。如沒有此屬性，Mastra 每次只會向其傳入一段文字。
- `maxBatchSize`：Provider 每次呼叫可接受的最大陣列大小。Mastra 會將較大的請求拆分成此大小的區塊，並平行傳送。請將其設定為 Provider 文件列明的限制（例如 OpenAI 為 2048、Cohere 為 96、Voyage 為 128）。省略此屬性則會在一個請求中傳送所有待處理文字。

```typescript
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { PineconeVector } from '@mastra/pinecone'
import { embedMany } from 'ai'
import { openai } from '@ai-sdk/openai'

const model = openai.embedding('text-embedding-3-small')

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  vectorStore: new PineconeVector({
    apiKey: process.env.PINECONE_API_KEY,
    index: 'workspace-index',
  }),
  embedder: Object.assign(
    async (texts: string[]) => {
      const { embeddings } = await embedMany({ model, values: texts })
      return embeddings
    },
    { batch: true as const, maxBatchSize: 2048 },
  ),
})
```

`Object.assign` 會將 `batch` 及 `maxBatchSize` 屬性加入 embedder 函式。Mastra 會將這些屬性讀取為 metadata，而不會傳遞給 Provider。

單一文字 embedder 仍然可用。函式簽名 `(text: string) => Promise<number[]>` 維持不變，因此現有程式碼毋須修改亦可繼續執行。

## 混合搜尋

同時設定 BM25 及向量搜尋，即可啟用混合模式，結合關鍵字配對與語義理解。

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  bm25: true,
  vectorStore: pineconeVector,
  embedder: embedderFn,
})
```

## 自訂索引名稱

搜尋索引名稱預設衍生自 Workspace ID。如要設定自訂名稱，請使用 `searchIndexName`：

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  bm25: true,
  searchIndexName: 'my_workspace_vectors',
})
```

索引名稱必須是有效的 SQL 識別碼：以字母或底線開頭，只包含字母、數字或底線，而且長度不得超過 63 個字元。

## 為內容建立索引

### 手動建立索引

使用 `workspace.index()`，以編程方式將內容加入搜尋索引。文件路徑會成為文件 ID。你亦可為每份文件傳入 metadata。

```typescript
// Basic indexing
await workspace.index('/docs/guide.md', 'Content of the guide...')

// Index with metadata for filtering or context
await workspace.index('/docs/api.md', apiDocContent, {
  metadata: {
    category: 'api',
    version: '2.0',
  },
})
```

手動建立索引適用於以下情況：

- 要建立索引的內容並非來自文件（例如資料庫記錄、API 回應）
- 你想在建立索引前預先處理內容或將其分塊
- 你需要為文件加入自訂 metadata

### 自動建立索引

設定 `autoIndexPaths`，即可在 Workspace 初始化時自動為文件建立索引。每個項目可以是目錄路徑（遞迴建立索引），亦可以是用於選擇性建立索引的 glob 模式。

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  bm25: true,
  autoIndexPaths: ['docs', 'support/faq'],
})

await workspace.init()
```

呼叫 `init()` 時，系統會讀取所有相符文件，並為其建立搜尋索引。文件路徑會成為文件 ID。

你可使用 glob 模式，為特定文件類型建立索引：

```typescript
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  bm25: true,
  autoIndexPaths: ['docs/**/*.md', 'support/**/*.txt'],
})
```

## 搜尋

使用 `workspace.search()` 尋找相關內容。結果會按相關性分數排序。

```typescript
const results = await workspace.search('password reset')

for (const result of results) {
  console.log(`${result.id}: ${result.score}`)
  console.log(result.content)
}
```

### 搜尋選項

你可使用選項自訂搜尋行為：

```typescript
const results = await workspace.search('authentication flow', {
  topK: 10,
  mode: 'hybrid',
  minScore: 0.5,
  vectorWeight: 0.5,
})
```

| 選項             | 說明                                                             |
| -------------- | -------------------------------------------------------------- |
| `topK`         | 傳回結果的最大數目。預設值：5                                                |
| `mode`         | 搜尋模式：`'bm25'`、`'vector'` 或 `'hybrid'`。預設會根據設定採用可用的最佳模式。        |
| `minScore`     | 篩除分數低於此門檻值（0-1）的結果。                                            |
| `vectorWeight` | 在混合模式中，向量分數相對於 BM25 分數的權重。0 = 全部採用 BM25、1 = 全部採用向量、0.5 = 兩者相同。 |

### 搜尋結果

每項結果均包含：

```typescript
interface SearchResult {
  id: string // Document ID (typically file path)
  content: string // The matching content
  score: number // Relevance score (0-1)
  lineRange?: {
    // Lines where the match was found
    start: number
    end: number
  }
  metadata?: Record<string, unknown> // Metadata stored with the document
  scoreDetails?: {
    // Score breakdown (hybrid mode only)
    vector?: number
    bm25?: number
  }
}
```

**理解分數：**

- 分數介乎 0 至 1，其中 1 代表完全相符
- BM25 分數會根據結果集中的最佳相符項目進行正規化
- 向量分數代表查詢與文件嵌入向量之間的餘弦相似度
- 在混合模式中，系統會使用 `vectorWeight` 參數合併分數

### 各模式的適用情況

| 模式       | 最適合           | 查詢範例                                                                    |
| -------- | ------------- | ----------------------------------------------------------------------- |
| `bm25`   | 確切詞彙、技術查詢、程式碼 | "useState hook"、"404 error"、"config.yaml"                               |
| `vector` | 概念查詢、自然語言     | "how to handle user authentication"、"best practices for error handling" |
| `hybrid` | 一般搜尋、未知查詢類型   | 大多數 Agent 使用情境                                                          |

## Agent tools

在 Workspace 上設定搜尋功能後，Agent 會獲得用於搜尋內容及建立內容索引的 Tool。詳情請參閱 [Workspace class 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)。

## 相關內容

- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)
- [RAG 概覽](https://mastra.zisheng.pro/zh-HK/guides/rag/overview)
- [Workspace class 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)