跳至主要內容

文件分塊與嵌入

處理之前，請先使用內容建立 MDocument 執行個體。你可以從不同格式初始化：

const docFromText = MDocument.fromText('Your plain text content...')
const docFromHTML = MDocument.fromHTML('<html>Your HTML content...</html>')
const docFromMarkdown = MDocument.fromMarkdown('# Your Markdown content...')
const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`)

文件處理
「文件處理」的直接連結

使用 chunk 將文件分割成容易處理的片段。Mastra 支援多種針對不同文件類型最佳化的分塊策略：

  • recursive：根據內容結構智慧分割
  • character：依字元進行簡單分割
  • token：考量 token 的分割
  • markdown：考量 Markdown 結構的分割
  • semantic-markdown：根據相關標題群組分割 Markdown
  • html：考量 HTML 結構的分割
  • json：考量 JSON 結構的分割
  • latex：考量 LaTeX 結構的分割
  • sentence：考量句子結構的分割
備註

每種策略都接受針對其分塊方式最佳化的不同參數。

以下是使用 recursive 策略的範例：

const chunks = await doc.chunk({
  strategy: 'recursive',
  maxSize: 512,
  overlap: 50,
  separators: ['\n'],
  extract: {
    metadata: true, // Optionally extract metadata
  },
})

若文字內容必須保留句子結構，可依照以下範例使用 sentence 策略：

const chunks = await doc.chunk({
  strategy: 'sentence',
  maxSize: 450,
  minSize: 50,
  overlap: 0,
  sentenceEnders: ['.'],
})

若 Markdown 文件必須保留各區段之間的語意關係，可依照以下範例使用 semantic-markdown 策略：

const chunks = await doc.chunk({
  strategy: 'semantic-markdown',
  joinThreshold: 500,
  modelName: 'gpt-3.5-turbo',
})
備註

擷取 metadata 可能會呼叫 LLM，因此請確認已設定 API 金鑰。

如需深入了解分塊策略，請參閱 chunk() 參考文件。

產生嵌入向量
「產生嵌入向量」的直接連結

使用你偏好的 Provider 將片段轉換成嵌入向量。Mastra 透過模型路由器支援嵌入模型。

使用模型路由器
「使用模型路由器」的直接連結

最簡單的方式是搭配 provider/model 字串使用 Mastra 模型路由器：

import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
import { embedMany } from 'ai'

const { embeddings } = await embedMany({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  values: chunks.map(chunk => chunk.text),
})

Mastra 支援 OpenAI 與 Google 的嵌入模型。完整的支援模型清單請參閱嵌入參考文件。

模型路由器會自動從環境變數偵測 API 金鑰。

嵌入函式會傳回向量，也就是代表文字語意的數值陣列，可直接用於向量資料庫中的相似度搜尋。

設定嵌入向量維度
「設定嵌入向量維度」的直接連結

嵌入模型通常會輸出固定維度的向量（例如 OpenAI 的 text-embedding-3-small 為 1536 維）。 部分模型支援降低維度，有助於：

  • 降低向量資料庫的儲存空間需求
  • 降低相似度搜尋的運算成本

以下是部分支援的模型：

OpenAI（text-embedding-3 模型）：

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

const { embeddings } = await embedMany({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  options: {
    dimensions: 256, // Only supported in text-embedding-3 and later
  },
  values: chunks.map(chunk => chunk.text),
})

Google (text-embedding-001):

const { embeddings } = await embedMany({
  model: google('gemini-embedding-001', {
    outputDimensionality: 256, // Truncates excessive values from the end
  }),
  values: chunks.map(chunk => chunk.text),
})
向量資料庫相容性

儲存嵌入向量時，向量資料庫索引的設定必須符合嵌入模型的輸出維度。若維度不符，可能會發生錯誤或資料損毀。

範例：完整流程
「範例：完整流程」的直接連結

以下範例示範文件處理，以及使用兩個 Provider 產生嵌入向量：

import { embedMany } from 'ai'

import { MDocument } from '@mastra/rag'

// Initialize document
const doc = MDocument.fromText(`
  Climate change poses significant challenges to global agriculture.
  Rising temperatures and changing precipitation patterns affect crop yields.
`)

// Create chunks
const chunks = await doc.chunk({
  strategy: 'recursive',
  maxSize: 256,
  overlap: 50,
})

// Generate embeddings with OpenAI
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

const { embeddings } = await embedMany({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  values: chunks.map(chunk => chunk.text),
})

// OR

// Generate embeddings with Cohere
const { embeddings } = await embedMany({
  model: 'cohere/embed-english-v3.0',
  values: chunks.map(chunk => chunk.text),
})

// Store embeddings in your vector database
await vectorStore.upsert({
  indexName: 'embeddings',
  vectors: embeddings,
})

如需其他分塊策略與嵌入設定範例，請參閱：

如需向量資料庫與嵌入的詳細資訊，請參閱：

On this page