Mastra 의미적 회상

친구에게 지난 주말에 뭘 했는지 물어보면, 그들은 "지난 주말"과 관련된 사건들을 기억에서 검색한 다음 무엇을 했는지 말해줄 것입니다. 이것이 Mastra에서 의미적 회상이 작동하는 방식과 비슷합니다.

의미적 회상의 작동 원리

의미적 회상은 메시지가 더 이상 최근 대화 기록에 없을 때 에이전트가 더 긴 상호작용에서 컨텍스트를 유지하도록 도와주는 RAG 기반 검색입니다.

메시지의 벡터 임베딩을 사용하여 유사성 검색을 수행하고, 다양한 벡터 저장소와 통합되며, 검색된 메시지 주변의 구성 가능한 컨텍스트 윈도우를 가집니다.

이 기능이 활성화되면, 새로운 메시지들이 의미적으로 유사한 메시지를 찾기 위해 벡터 DB를 쿼리하는 데 사용됩니다.

LLM으로부터 응답을 받은 후, 모든 새로운 메시지들(사용자, 어시스턴트 및 도구 호출/결과)이 나중의 상호작용에서 회상될 수 있도록 벡터 DB에 삽입됩니다.

빠른 시작

의미적 회상은 기본적으로 활성화되어 있으므로, 에이전트에 메모리를 제공하면 포함됩니다:

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
 
const agent = new Agent({
  name: "SupportAgent",
  instructions: "당신은 도움이 되는 지원 에이전트입니다.",
  model: openai("gpt-4o"),
  memory: new Memory(),
});

회상 구성

의미적 회상 동작을 제어하는 세 가지 주요 매개변수는 다음과 같습니다:

topK: 검색할 의미적으로 유사한 메시지의 수
messageRange: 각 일치 항목과 함께 포함할 주변 컨텍스트의 양
scope: 현재 스레드 내에서 검색할지 또는 리소스가 소유한 모든 스레드에서 검색할지 여부. scope: 'resource'를 사용하면 에이전트가 사용자의 모든 과거 대화에서 정보를 회상할 수 있습니다.

const agent = new Agent({
  memory: new Memory({
    options: {
      semanticRecall: {
        topK: 3, // 가장 유사한 메시지 3개 검색
        messageRange: 2, // 각 일치 항목 전후로 2개 메시지 포함
        scope: 'resource', // 이 사용자의 모든 스레드에서 검색
      },
    },
  }),
});

참고: 현재 의미적 회상의 scope: 'resource'는 다음 저장소 어댑터에서 지원됩니다: LibSQL, Postgres, Upstash.

저장소 구성

의미적 회상은 메시지와 임베딩을 저장하기 위해 저장소와 벡터 DB에 의존합니다.

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 
const agent = new Agent({
  memory: new Memory({
    // 생략된 경우 기본 저장소 DB
    storage: new LibSQLStore({
      url: "file:./local.db",
    }),
    // 생략된 경우 기본 벡터 DB
    vector: new LibSQLVector({
      connectionUrl: "file:./local.db",
    }),
  }),
});

저장소/벡터 코드 예제:

임베더 설정

의미적 회상은 메시지를 임베딩으로 변환하기 위해 임베딩 모델에 의존합니다. AI SDK와 호환되는 모든 임베딩 모델을 지정할 수 있습니다.

FastEmbed(로컬 임베딩 모델)를 사용하려면 @mastra/fastembed를 설치하세요:

npm install @mastra/fastembed

그 다음 메모리에서 구성하세요:

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { fastembed } from "@mastra/fastembed";
 
const agent = new Agent({
  memory: new Memory({
    // ... 기타 메모리 옵션
    embedder: fastembed,
  }),
});

또는 OpenAI와 같은 다른 제공업체를 사용하세요:

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
const agent = new Agent({
  memory: new Memory({
    // ... 기타 메모리 옵션
    embedder: openai.embedding("text-embedding-3-small"),
  }),
});

비활성화

의미적 회상을 사용하면 성능에 영향을 미칩니다. 새로운 메시지들이 임베딩으로 변환되고 새로운 메시지가 LLM에 전송되기 전에 벡터 데이터베이스를 쿼리하는 데 사용됩니다.

의미적 회상은 기본적으로 활성화되어 있지만 필요하지 않을 때 비활성화할 수 있습니다:

const agent = new Agent({
  memory: new Memory({
    options: {
      semanticRecall: false,
    },
  }),
});

다음과 같은 시나리오에서 의미적 회상을 비활성화하고 싶을 수 있습니다:

대화 기록이 현재 대화에 대한 충분한 컨텍스트를 제공할 때
실시간 양방향 오디오와 같은 성능에 민감한 애플리케이션에서 임베딩 생성과 벡터 쿼리 실행의 추가 지연 시간이 눈에 띄는 경우

회상된 메시지 보기

추적이 활성화되면, 의미적 회상을 통해 검색된 모든 메시지가 최근 대화 기록(구성된 경우)과 함께 에이전트의 추적 출력에 나타납니다.

메시지 추적 보기에 대한 자세한 정보는 검색된 메시지 보기를 참조하세요.

2025년 7월 26일 기준 번역
by dongne.lab@gmail.com

의미적 회상(Semantic Recall)