볼록한 저장
Convex 스토리지 구현은 다음을 사용하여 서버리스 스토리지 솔루션을 제공합니다.Convex, 실시간 동기화 및 자동 캐싱 기능을 갖춘 풀 스택 TypeScript 개발 플랫폼입니다.
:::warning[관측성이 지원되지 않음]
Convex 스토리지는 Observability 도메인을 지원하지 않습니다. MastraStorageExporter의 Trace를 Convex에 유지할 수 없으며, Convex를 유일한 스토리지 Provider로 사용하는 경우 Studio의 Observability 기능이 작동하지 않습니다. Observability을 활성화하려면 복합 스토리지를 사용하여 Observability 데이터를 ClickHouse와 같이 지원되는 Provider로 라우팅하세요.
:::
:::warning[레코드 크기 제한] Convex의 최대 레코드 크기는 1 MiB입니다. 이미지와 같이 base64로 인코딩된 첨부 파일이 포함된 메시지를 저장하면 이 제한을 초과할 수 있습니다. 첨부 파일을 S3, Cloudflare R2 또는 Convex 파일 스토리지와 같은 외부 스토리지에 업로드하는 방법을 비롯한 해결 방법은 대용량 첨부 파일 처리를 참조하세요. :::
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/convex@latest
pnpm add @mastra/convex@latest
yarn add @mastra/convex@latest
bun add @mastra/convex@latest
볼록한 설정볼록한 설정에 대한 직접 링크
ConvexStore를 사용하기 전에 Convex 프로젝트에서 Convex 스키마와 스토리지 핸들러를 설정하세요.
아래 스키마 예제에는 전체 ConvexStore 및 ConvexServerCache 설정이 포함되어 있습니다. ConvexStore만 사용하는 경우 mastraCacheTable과 mastraCacheListItemsTable을 생략하고, ConvexServerCache를 사용하는 경우에는 해당 테이블을 포함하고 캐시 핸들러를 생성하세요.
1. 볼록 스키마 설정1. 볼록 스키마 설정에 대한 직접 링크
~ 안에convex/schema.ts:
import { defineSchema } from 'convex/server'
import {
mastraThreadsTable,
mastraMessagesTable,
mastraResourcesTable,
mastraWorkflowSnapshotsTable,
mastraScoresTable,
mastraObservationalMemoryTable,
mastraVectorIndexesTable,
mastraVectorsTable,
mastraCacheTable,
mastraCacheListItemsTable,
mastraDocumentsTable,
} from '@mastra/convex/schema'
export default defineSchema({
mastra_threads: mastraThreadsTable,
mastra_messages: mastraMessagesTable,
mastra_resources: mastraResourcesTable,
mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
mastra_scorers: mastraScoresTable,
mastra_observational_memory: mastraObservationalMemoryTable,
mastra_vector_indexes: mastraVectorIndexesTable,
mastra_vectors: mastraVectorsTable,
mastra_cache: mastraCacheTable,
mastra_cache_list_items: mastraCacheListItemsTable,
mastra_documents: mastraDocumentsTable,
})
2. 스토리지 핸들러 생성2. 스토리지 핸들러 생성에 대한 직접 링크
~ 안에convex/mastra/storage.ts:
import { mastraStorage } from '@mastra/convex/server'
export const handle = mastraStorage
ConvexServerCache를 사용하는 경우 convex/mastra/cache.ts를 생성하세요.
import { mastraCache } from '@mastra/convex/server'
export const handle = mastraCache
3. Convex에 배포3. Convex에 배포에 대한 직접 링크
npx convex dev
# or for production
npx convex deploy
용법용법에 대한 직접 링크
import { ConvexServerCache, ConvexStore } from '@mastra/convex'
const storage = new ConvexStore({
id: 'convex-storage',
deploymentUrl: process.env.CONVEX_URL!,
adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
})
const cache = new ConvexServerCache({
deploymentUrl: process.env.CONVEX_URL!,
adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
})
ConvexStore 매개변수ConvexStore 매개변수에 대한 직접 링크
deploymentUrl:
adminAuthToken:
storageFunction?:
ConvexServerCache 매개변수ConvexServerCache 매개변수에 대한 직접 링크
deploymentUrl:
adminAuthToken:
cacheFunction?:
requestTimeoutMs?:
keyPrefix?:
ttlMs?:
생성자 예생성자 예에 대한 직접 링크
import { ConvexServerCache, ConvexStore } from '@mastra/convex'
// Basic configuration
const store = new ConvexStore({
id: 'convex-storage',
deploymentUrl: 'https://your-project.convex.cloud',
adminAuthToken: 'your-admin-token',
})
// With custom storage function path
const storeCustom = new ConvexStore({
id: 'convex-storage',
deploymentUrl: 'https://your-project.convex.cloud',
adminAuthToken: 'your-admin-token',
storageFunction: 'custom/path:handler',
})
// Server cache for durable stream replay and response caching
const cache = new ConvexServerCache({
deploymentUrl: 'https://your-project.convex.cloud',
adminAuthToken: 'your-admin-token',
cacheFunction: 'mastra/cache:handle',
})
서버 캐시서버 캐시에 대한 직접 링크
ConvexServerCacheConvex와 Mastra의 서버 캐시 계약을 구현합니다. 재개 가능한 내구성 Agent 스트림, Workflow 스트림 재생 또는 응답 캐싱과 같은 기능에 대해 내구성 있는 캐시 상태를 원할 때 사용합니다.
ConvexServerCache목록 항목을 별도의 Convex 문서로 저장합니다. 이렇게 하면 하나의 문서 내에서 스트림 재생 목록이 커지는 것을 방지하고 Convex의 레코드 크기 제한 내에서 유지하는 데 도움이 됩니다.
각 스칼라 캐시 값과 각 목록 항목은 하나의 Convex 행으로 저장되며 Convex의 행 크기 제한 내에 있어야 합니다. 범위를 재생할 때 매우 큰 목록은 여전히 Convex 쿼리 제한으로 제한됩니다.
캐시 정리와 clear()는 제한된 배치 단위로 실행됩니다. 단일 클라이언트 호출은 최대 1,000개의 Convex 변경 작업을 순회할 수 있으며, 각 변경 작업은 최대 25개의 목록 항목을 처리합니다. clear()가 키를 정리하는 동안에는 정리가 끝날 때까지 해당 키에 대한 읽기 결과가 비어 있을 수 있습니다.
매우 큰 캐시 네임스페이스의 경우 점진적으로 지우거나 더 좁은 접두사를 사용하여 장기 실행 정리 작업을 방지합니다.
배치 정리 중에는 캐시 메타데이터가 일시적으로 내부 deleted 상태가 됩니다. 다음 정리 단계에서 해당 행을 제거합니다. clear()가 끝날 때까지 동일한 접두사로 새 값을 쓰지 마세요.
clear()는 저장된 keyPrefix가 구성된 keyPrefix와 정확히 일치하는 행만 제거합니다. 문자열 접두사 일치 방식으로 중첩 접두사를 지우지는 않습니다. 각 listPush()는 캐시에 구성된 ttlMs를 사용하여 목록 TTL을 갱신합니다.
clear()가 배포의 모든 캐시 키를 제거하도록 의도한 경우가 아니라면 비어 있지 않은 keyPrefix를 사용하세요. 만료된 목록 행은 읽기 및 쓰기 과정에서 점진적으로 회수됩니다. clear()는 해당 접두사의 모든 행을 제거합니다.
ConvexServerCache중간 빈도 이벤트의 내구성 있는 재생에 가장 적합합니다. 빈도가 높은 토큰 스트림의 경우 이벤트를 일괄 처리하거나 지연 시간이 짧은 캐시 백엔드를 사용하는 것이 좋습니다.
ConvexServerCache분산 pub/sub 전송을 대체하지 않습니다. 앱에 실시간 크로스 프로세스 이벤트 전달이 필요한 경우 프로덕션 게시/구독 백엔드를 별도로 구성하세요.
추가 참고사항추가 참고사항에 대한 직접 링크
스키마 관리스키마 관리에 대한 직접 링크
스토리지 구현에서는 각 Mastra 도메인에 대해 유형이 지정된 Convex 테이블을 사용합니다.
| 도메인 | Convex 테이블 | 목적 |
|---|---|---|
| 스레드 | mastra_threads | 대화 스레드 |
| 메시지 | mastra_messages | 채팅 메시지 |
| 리소스 | mastra_resources | 사용자 작업 Memory |
| 관찰 Memory | mastra_observational_memory | 관찰 Memory 생성 결과 |
| Workflow | mastra_workflow_snapshots | Workflow 상태 |
| 채점기 | mastra_scorers | 평가 데이터 |
| 캐시 | mastra_cache | 캐시 값, 카운터, 목록 메타데이터 |
| 캐시 항목 | mastra_cache_list_items | 캐시 목록 항목 |
| 대체 항목 | mastra_documents | 알 수 없는 테이블 |
관찰 기억관찰 기억에 대한 직접 링크
ConvexStore는 관찰 Memory를 지원합니다. Convex 스키마에 mastraObservationalMemoryTable을 추가하고 npx convex deploy로 다시 배포하여 활성화하세요. 이 테이블이 추가되기 전에 생성된 기존 배포에도 동일한 스키마 업데이트가 필요합니다.
건축학건축학에 대한 직접 링크
모든 유형의 테이블에는 다음이 포함됩니다.
- Mastra 레코드 ID를 위한
id필드(Convex가 자동 생성하는_id와 별개) - Mastra ID로 효율적으로 조회하기 위한
by_record_id인덱스 이 디자인은 Convex의 자동 인덱싱 및 실시간 기능을 사용하면서 Mastra의 스토리지 계약과의 호환성을 보장합니다.
환경변수환경변수에 대한 직접 링크
배포에 대해 다음 환경 변수를 설정합니다.
CONVEX_URL: Convex 배포 URLCONVEX_ADMIN_KEY: 관리자 인증 토큰(Convex 대시보드에서 가져오기)