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

# summarizeConversation()

獨立的 `summarizeConversation()` 函式會一次完成對話摘要。它使用支援 [Observational Memory](https://mastra.zisheng.pro/zh-TW/reference/memory/observational-memory) 的相同 Observer 管線濃縮你傳入的訊息：不必將 Observational Memory 附加至 Agent，也不會讀取或寫入儲存空間。

系統不會將任何內容寫回 Memory。摘要及擷取的值會回傳給你（以及每個 extractor 的 `onExtracted` hook），由你決定儲存位置，例如自己的資料庫。

當你已經取得訊息，且想明確控制摘要內容時，請使用此函式。若是由 ID 識別的已儲存執行緒，請使用 [`Memory.summarizeThread()`](https://mastra.zisheng.pro/zh-TW/reference/memory/summarizeThread)，由它為你載入訊息。

## 使用範例

```typescript
import { summarizeConversation } from '@mastra/memory'

const result = await summarizeConversation({
  model: 'openai/gpt-5-mini',
  messages,
  instructions: 'Summarize this voicemail call for the business owner.',
})
```

## 參數

**model** (`string | LanguageModel | DynamicModel`): 執行摘要的模型，例如 '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_' 這類 router 字串。

**messages** (`MastraDBMessage[]`): 要摘要的對話。為空時，函式會回傳空白結果而不呼叫模型。

**instructions** (`string`): 附加到摘要器 system prompt 的額外指引，例如應著重的內容或摘要的閱讀對象。

**extract** (`Extractor[]`): 要在對話上執行的 extractor。具有 Zod schema 的 extractor 會以後續結構化輸出呼叫執行；不含 schema 的 extractor 則會行內擷取。每個 extractor 的 onExtracted hook 都會收到擷取的值。

**threadId** (`string`): 對話所屬的執行緒。預設為 messages 中找到的第一個 threadId，並會傳給 extractor context。

**resourceId** (`string`): 對話所屬的資源（使用者）。預設為 messages 中找到的第一個 resourceId，並會傳給 extractor context。

**memory** (`Memory`): 轉送至 extractor context 的 Memory 執行個體。透過 Memory.summarizeThread() 呼叫時會自動設定。

**mastra** (`Mastra`): 用來解析自訂 gateway 模型的 Mastra 執行個體。透過 Memory.summarizeThread() 呼叫時會自動設定。

**requestContext** (`RequestContext`): 轉送至摘要模型與 extractor hook 的 request context。

**abortSignal** (`AbortSignal`): 取消摘要呼叫的訊號。

## 回傳值

**summary** (`string`): 從對話產生、以密集項目符號呈現的濃縮 observation。

**extracted** (`Record<string, unknown>`): extract extractor 產生的值，以 extractor slug 作為 key。

**extractionFailures** (`{ slug: string; error: string }[]`): 未能產生有效值的 extractor 及其原因。只有至少一個 extractor 失敗時才會存在。

**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): 摘要呼叫的 token 使用量。

## 延伸使用範例

下列範例會根據應用程式已持有的訊息，摘要進行中的語音工作階段，並擷取結構化記錄：

```typescript
import { summarizeConversation, Extractor } from '@mastra/memory'
import type { MastraDBMessage } from '@mastra/core/agent'
import { z } from 'zod'
import { sessionRecords } from './db'

const sessionSummary = new Extractor({
  name: 'session-summary',
  instructions: 'Return a concise summary of the session.',
  schema: z.object({
    summary: z.string(),
    sentiment: z.enum(['positive', 'neutral', 'negative']),
    followUps: z.array(z.string()),
  }),
  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
  onExtracted: async ({ current, threadId }) => {
    await sessionRecords.upsert({ sessionId: threadId, record: current })
  },
})

export async function onSessionEnd(messages: MastraDBMessage[]) {
  const { summary, extracted, extractionFailures } = await summarizeConversation({
    model: 'openai/gpt-5-mini',
    messages,
    instructions: 'Summarize this support session for the account manager.',
    extract: [sessionSummary],
  })

  if (extractionFailures?.length) {
    console.warn('Some extractors failed', extractionFailures)
  }

  return { summary, extracted }
}
```

### 相關內容

- [.summarizeThread()](https://mastra.zisheng.pro/zh-TW/reference/memory/summarizeThread)
- [Memory 類別參考](https://mastra.zisheng.pro/zh-TW/reference/memory/memory-class)
- [Observational Memory](https://mastra.zisheng.pro/zh-TW/reference/memory/observational-memory)