03-embedding-readme

Dec 7, 2025

Embedding Module

임베딩 생성 및 관리를 담당하는 모듈입니다.

목차

  1. 개요

  2. 아키텍처

  3. 주요 함수

  4. API 엔드포인트

  5. 설정

개요

임베딩이란?

텍스트를 숫자 배열(벡터)로 변환하는 것입니다. 이를 통해:

  • 의미적 유사도 검색: "투자 회의"를 검색하면 "시리즈A 논의", "펀딩 미팅" 등도 찾을 수 있음

  • 키워드 매칭의 한계 극복: 단어가 달라도 의미가 비슷하면 찾을 수 있음

사용 모델

  • 모델: OpenAI text-embedding-3-small

  • 차원: 1536

  • 비용: $0.02 / 1M tokens

아키텍처

┌─────────────────────────────────────────────────────────────┐
│                      lib/embedding/                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  config.ts          설정 (모델, 차원, 배치 크기)              │
│       ↓                                                      │
│  normalizer.ts      L2 정규화 (벡터 길이를 1로)               │
│       ↓                                                      │
│  generator.ts       OpenAI API 호출                          │
│       ↓                                                      │
│  memory-embedder.ts MemoryNode에 임베딩 추가                 │
│       ↓                                                      │
│  batch-processor.ts FalkorDB 기존 메모리 일괄 처리           │
│                                                              │
└─────────────────────────────────────────────────────────────┘

주요 함수

저수준 함수 (generator.ts)

// 단일 텍스트 → 벡터
const embedding = await generateEmbedding("회의 내용 요약");
// → [0.023, -0.156, 0.891, ...] (1536개)

// 여러 텍스트 → 벡터 배열
const embeddings = await generateEmbeddings(["텍스트1", "텍스트2"]);

메모리 임베딩 함수 (memory-embedder.ts)

// 기존 MemoryNode에 임베딩 추가
const withEmbed = await embedMemory(existingMemory);

// LLM 추출 결과 → 완전한 MemoryNode 생성
const memory = await createMemoryWithEmbedding(extractedMemory, {
  sourceId: "email_123",
  emailDate: new Date(),
});

배치 처리 함수 (batch-processor.ts)

// FalkorDB에서 임베딩 없는 메모리 일괄 처리
const result = await processExistingMemories(client, {
  batchSize: 50,
  onProgress: (p) => console.log(`${p.processed}/${p.total}`),
});

API 엔드포인트

POST /api/embeddings/generate

텍스트를 임베딩으로 변환합니다.

단일 텍스트:

// Request
{ "text": "회의 내용 요약" }

// Response
{
  "success": true,
  "embedding": [0.023, -0.156, ...],
  "dimension": 1536,
  "usage": { "estimatedTokens": 10, "estimatedCost": 0.0000002 }
}

여러 텍스트:

// Request
{ "texts": ["텍스트1", "텍스트2", "텍스트3"] }

// Response
{
  "success": true,
  "embeddings": [[...], [...], [...]],
  "count": 3,
  "dimension": 1536
}

POST /api/embeddings/batch

FalkorDB의 기존 메모리에 임베딩을 추가합니다.

// Request
{
  "batchSize": 50,
  "maxMemories": 1000,
  "batchDelayMs": 500
}

// Response
{
  "success": true,
  "result": {
    "totalFound": 1000,
    "totalProcessed": 1000,
    "totalSucceeded": 998,
    "totalFailed": 2,
    "failedIds": ["mem_042", "mem_089"],
    "totalTimeMs": 45000
  }
}

GET /api/embeddings/batch

배치 처리 상태를 확인합니다.

// Response
{
  "success": true,
  "status": {
    "openAIConfigured": true,
    "falkorDBConnected": true,
    "memoriesWithoutEmbeddings": 150
  }
}

설정

환경 변수

# 필수
OPENAI_API_KEY=sk-...

# 선택 (기본값 있음)
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_BATCH_SIZE=100
EMBEDDING_MAX_RETRIES=3
EMBEDDING_RETRY_DELAY_MS=1000

설정 객체

import { embeddingConfig } from '@/lib/embedding';

console.log(embeddingConfig);
// {
//   model: "text-embedding-3-small",
//   dimension: 1536,
//   batchSize: 100,
//   maxRetries: 3,
//   retryDelayMs: 1000,
//   maxInputLength: 8191
// }

데이터 흐름

새 메모리 생성 시

이메일
  ↓ (Gmail API)
원본 이메일
  ↓ (정규화)
정규화된 이메일
  ↓ (LLM 추출)
ExtractedMemory { content, category, importance, ... }
  ↓ (createMemoryWithEmbedding)
MemoryNode { id, content, embedding, createdAt, ... }
  ↓ (Phase 4에서 구현)
FalkorDB에 저장

기존 메모리 처리 시

FalkorDB
  ↓ (getMemoriesWithoutEmbeddings)
{ id, content }[]  (임베딩 없는 메모리들)
  ↓ (generateEmbeddings)
{ id, embedding }[]
  ↓ (storeEmbedding)
FalkorDB 업데이트

‹

›