업스태시 스토리지

Upstash 스토리지 구현은 Upstash의 Redis 호환 키-값 저장소를 사용하여 서버리스 친화적인 스토리지 솔루션을 제공합니다.

:::warning[가격]

Upstash와 함께 Mastra를 사용할 때 종량제 요금제는 Agent 대화 중 생성되는 Redis 명령이 많아 예기치 않은 고비용을 초래할 수 있습니다. 예측 가능한 비용을 위해 고정 요금제를 권장합니다. 자세한 내용은 Upstash 요금을, 관련 배경은 GitHub 이슈 #5850을 참조하세요. :::

:::warning[관측성이 지원되지 않음]

Upstash 스토리지는 Observability 도메인을 지원하지 않습니다. MastraStorageExporter의 Trace를 Upstash에 영구 저장할 수 없으며, Upstash를 유일한 스토리지 Provider로 사용하면 Studio의 Observability 기능이 작동하지 않습니다. Observability를 활성화하려면 복합 스토리지를 사용하여 Observability 데이터를 ClickHouse와 같이 지원되는 Provider로 라우팅하세요. :::

설치

npm

npm install @mastra/upstash@latest

pnpm

pnpm add @mastra/upstash@latest

Yarn

yarn add @mastra/upstash@latest

Bun

bun add @mastra/upstash@latest

용법

import { UpstashStore } from '@mastra/upstash'

const storage = new UpstashStore({
  id: 'upstash-storage',
  url: process.env.UPSTASH_URL,
  token: process.env.UPSTASH_TOKEN,
})

매개변수

url:

string

Upstash Redis URL

token:

string

Upstash Redis 인증 토큰

prefix?:

string

= mastra:

저장되는 모든 항목의 키 접두사

추가 참고사항

주요 구조

Upstash 스토리지 구현은 키-값 구조를 사용합니다.

• 스레드 키:{prefix}thread:{threadId}
• 메시지 키:{prefix}message:{messageId}
• 메타데이터 키:{prefix}metadata:{entityId}

서버리스 이점

Upstash 스토리지는 특히 서버리스 배포에 적합합니다.

• 연결 관리가 필요하지 않습니다
• 요청당 지불 가격
• 글로벌 복제 옵션
• 엣지 호환

데이터 지속성

Upstash는 다음을 제공합니다.

• 자동 데이터 지속성
• 특정 시점 복구
• 지역 간 복제 옵션

성능 고려 사항

최적의 성능을 위해서는:

• 적절한 키 접두사를 사용하여 데이터 구성
• Redis Memory 사용량 모니터링
• 필요한 경우 데이터 만료 정책을 고려하세요.

사용예

Agent에 Memory 추가

Agent에 Upstash Memory를 추가하려면 Memory 클래스를 사용하고, UpstashStore를 사용하는 새 storage 키와 UpstashVector를 사용하는 새 vector 키를 생성하세요. 구성은 원격 서비스나 로컬 설정 중 하나를 가리킬 수 있습니다.

src/mastra/agents/example-upstash-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { UpstashStore } from '@mastra/upstash'

export const upstashAgent = new Agent({
  id: 'upstash-agent',
  name: 'Upstash Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    options: {
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
})

Agent 사용

memoryOptions를 사용하여 이 요청의 회상 범위를 지정하세요. lastMessages: 5를 설정하여 최근성 기반 회상을 제한하고, semanticRecall을 사용하여 가장 관련성 높은 메시지를 topK: 3개 가져오세요. 각 일치 항목 주변의 컨텍스트를 위해 인접 메시지 messageRange: 2개도 포함합니다.

src/test-upstash-agent.ts

import 'dotenv/config'

import { mastra } from './mastra'

const threadId = '123'
const resourceId = 'user-456'

const agent = mastra.getAgent('upstashAgent')

const message = await agent.stream('My name is Mastra', {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
})

await message.textStream.pipeTo(new WritableStream())

const stream = await agent.stream("What's my name?", {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
  memoryOptions: {
    lastMessages: 5,
    semanticRecall: {
      topK: 3,
      messageRange: 2,
    },
  },
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}