Docusaurus MAI에서 벡터를 활용한 WordPress AI 채팅까지

여러 프로젝트를 거치며 "채팅"이 어떻게 진화해 왔는지, 최종적으로 도달한 세 가지 아키텍처, 각각의 장단점, 그리고 프로젝트별로 어떤 것을 선택해야 하는지에 대한 여정입니다.

요약 (TL;DR) — 각기 다른 대상에 적합한 세 가지 작동 방식:

1. 정적 JSON 인덱스 (Static JSON index): Docusaurus/Vercel 사이트 내부(MAI) — 인프라 구축 불필요, 즉시 배포 가능.
2. Postgres + pgvector 호스팅 RAG 서비스 (Neon) — 대규모 환경에서의 실제 의미론적 검색 (Semantic Search), 다중 사용자 지원.
3. 자체 포함형 WordPress 플러그인 (Self-contained WordPress plugin): 사이트 DB 내에 벡터를 포함 (Grekai Chat) — 추가 인프라 없이 모든 WP에 설치 가능.

타임라인 (The timeline)

각 단계는 이전 단계의 한계를 해결했지만, 어느 하나가 다른 것을 대체하지는 않았습니다 — 이들은 서로 다른 배포 환경을 목표로 하므로, 세 가지 모두 여전히 유효한 선택지입니다.

1단계 — Docusaurus 기반의 MAI (정적 인덱스)

Vercel의 Docusaurus 3.8 문서 사이트 내에 배포된 문서 어시스턴트("MAI")입니다.

• 빌드 전 단계(Pre-build step)에서 모든 마크다운(Markdown)을 단일 docs-index.json으로 컴파일하며, 이는 서버리스 함수(vercel.json의 includeFiles)와 함께 번들링됩니다.
• 검색(Retrieval)은 해당 인덱스를 대상으로 함수 내부의 메모리 상에서 실행되며, 근거가 되는 컨텍스트(Grounded context)가 선택된 제공업체(Provider)로 전송됩니다.
• API 키는 방문자 본인의 것을 사용하며, 클라이언트 측에서 암호화됩니다 (IndexedDB의 기기별 키 사용).

장점 (Pros)

• 데이터베이스 불필요, 추가 인프라 불필요 — 사이트와 함수만 있으면 됩니다.
• 저렴하고 배포가 빠르며, 인덱스가 문서와 함께 버전 관리됩니다 (배포 시 재빌드).
• 다중 제공업체(Multi-provider) 지원, 서버 측 비밀 키(Secrets)가 필요 없음.

단점 (Cons)

• 인덱스가 배포될 때마다 재빌드되며, 메모리에 전체가 로드됩니다 (loaded whole into memory).
• 검색 품질에 한계가 있습니다 (사전 계산되지 않는 한 진정한 ANN 벡터 인덱스가 없음).
• 콘텐츠가 몇 MB를 넘어서면 확장(Scale)이 불가능하며, 사용자별 데이터, 히스토리 또는 인증(Auth) 기능이 없습니다.

2단계 — Neon Postgres + pgvector (호스팅된 RAG 서비스)

진정한 의미론적 검색(Semantic search), 확장성(Scale), 그리고 다중 사용자 계정을 확보하기 위한 다음 단계는 Postgres + pgvector를 기반으로 하는 전용 RAG 서비스였습니다 (운영 환경에서는 Neon을 사용하고, 로컬에서는 임베디드 pgserver를 사용함).

• 벡터는 langchain_pg_embedding (vector(1536))에 저장되며, 실제 벡터 인덱스(ANN)를 통해 검색됩니다. 이는 대규모 코퍼스(Corpora)에서도 빠릅니다.
• 계정 (Accounts): app_users (scrypt 비밀번호 해시), user_secrets (사용자별 API 키, AES-256-GCM 적용, 서버 측에서만 복호화됨), user_data (사용자별 JSON).

장점 (Pros)

• 대규모 또는 계속 성장하는 콘텐츠로 확장(Scales) 가능한 진정한 의미론적 검색.
• 멀티 테넌트 (Multi-tenant): 각기 다른 암호화된 키와 데이터를 가진 수많은 사용자 지원.
• 쿼리가 가능한 내구성 있는 데이터베이스; 인증(Auth) / 벡터 / 데이터의 깔끔한 분리.

단점 (Cons)

• 호스팅된 Postgres (Neon)와 이를 실행할 서비스가 모두 필요합니다 — 관리 요소(Moving parts)가 더 많아집니다.
• 운영(Ops) 및 비용 문제; 단일 소규모 사이트에는 **과잉 사양 (Overkill)**입니다.
• 단순히 "설치"하는 것이 아니라, 직접 운영해야 하는 인프라입니다.

3단계 — Grekai Chat (WordPress 플러그인, WP DB 내 벡터 저장)

채팅을 어떤 클라이언트의 WordPress 사이트에도 바로 적용할 수 있는 **드롭인 제품 (Drop-in product)**으로 만들기 위해, 벡터를 WordPress 데이터베이스 자체 내부로 이동시켰습니다 — 외부 DB나 실행할 별도의 서비스가 필요 없습니다.

• 플러그인을 활성화하면 두 개의 테이블이 생성됩니다: wp_gk_chat_chunks (각 구절의 임베딩 (embedding)이 JSON으로 저장됨) 및 wp_gk_chat_leads.
• **Gemini gemini-embedding-001**을 통해 임베딩을 생성하며, 검색 (retrieval)은 청크 (chunks)에 대해 PHP에서 브루트 포스 코사인 유사도 (brute-force cosine) 방식으로 수행됩니다.
• 소유자가 자신의 API 키를 직접 제공합니다 (wp_options에 암호화되어 저장됨). 모든 데이터는 사이트 자체 DB에 머뭅니다. 리드 캡처 (lead capture), RTL (Right-to-Left), 어뷰징 방지, i18n (국제화) 기능이 추가되었습니다.

장점 (Pros)

• 모든 WordPress에 설치 가능하며, 추가 설정이 전혀 필요 없습니다 — 별도의 DB나 인프라가 필요하지 않습니다.
• 데이터가 사이트 소유자의 DB에 머뭅니다; GPL 라이선스이며 배포 가능합니다 (진정한 의미의 플러그인).
• 리드 생성 (lead generation) 및 퍼널 (funnel) 기능이 내장되어 있으며, 소유자가 자신의 키를 통해 비용을 제어합니다.

단점 (Cons)

• 브루트 포스 코사인 방식은 수만 개의 청크로 확장하기 어렵습니다 (소규모/중규모 사이트, 즉 수천 개의 구절까지는 적합합니다).
• WP DB는 벡터 DB (vector DB)가 아닙니다 — ANN (Approximate Nearest Neighbor) 인덱스가 없으며, 콘텐츠 변경 시 임베딩을 다시 실행해야 합니다.
• 호스트/런타임 제약 사항 (공유 호스팅, PHP 제한).

왜 플러그인에 pgvector를 사용하지 않나요? 제품의 목표는 "설정 없이 모든 WordPress에서 작동하는 것"입니다. 외부 Postgres를 요구하는 것은 이 목표를 깨뜨리고 모든 사이트 소유자에게 비용과 운영 부담을 떠넘기는 일이 됩니다. WP 사이트는 규모가 작거나 중간 정도이므로 브루트 포스 코사인으로도 충분히 빠릅니다. 또한 벡터 저장소는 교체 가능한 단일 클래스 (includes/class-vector-store.php)로 구현되어 있어, 규모가 커진 사이트는 플러그인의 나머지 부분을 건드리지 않고도 pgvector나 외부 벡터 DB를 가리키도록 설정할 수 있습니다.

비교 (Side-by-side)

차원 (Dimension)	1단계 · Docusaurus 정적 인덱스	2단계 · Neon + pgvector	3단계 · WP 플러그인 (DB 내 벡터)
벡터 저장 위치	함수와 함께 번들링된 JSON 파일	Postgres pgvector	wp_gk_chat_chunks (JSON)
...	...	...	...

프로젝트별 어떤 접근 방식이 적합할까요?

• 자체 문서/마케팅 사이트, 콘텐츠 변경이 거의 없음 → 1단계. 아직 필요하지 않은 벡터 DB를 구축하지 마세요.
• 멀티 테넌트 (Multi-tenant) SaaS, 대규모 지식 베이스, 사용자별 키/히스토리 → 2단계.
• 운영 부담 없이 어떤 WordPress 사이트에도 작동하는 채팅을 제공하고 싶음 → 3단계.

교훈 (Lessons learned)

1. 검증을 위해 단순하게 시작하세요. 정적 인덱스 (Static index)는 데이터베이스를 구축하기 전에 채팅과 UX를 검증하는 데 효과적이었습니다.
2. 벡터 저장소 (Vector store)를 교체 가능하게 유지하세요. 인터페이스 뒤에 하나의 클래스를 두면, 애플리케이션을 다시 작성하지 않고도 검색 (Retrieval) 방식(JSON → pgvector → 관리형 벡터 DB)을 업그레이드할 수 있습니다.
3. **아키텍처를 유행이 아닌 배포 대상 (Deployment target)에 맞추세요 — 정적 사이트 vs SaaS vs 배포 가능한 플러그인 — 외부 Postgres가 필요한 플러그인은 아무도 설치하지 않을 것입니다.
4. 브루트 포스 (Brute-force) 코사인 유사도 계산은 생각보다 오래 지속됩니다. 수천 개의 구절(Passages) 정도는 밀리초 단위로 처리됩니다. ANN/pgvector는 데이터 규모가 요구할 때만 사용하세요.
5. 모든 계층에서 키를 암호화하고 브라우저로 절대 전송하지 마세요 — IndexedDB (클라이언트), user_secrets (서버), wp_options (플러그인)는 모두 동일한 이유로 이를 각기 다른 방식으로 수행합니다.
6. BYOK (Bring-your-own-key) 방식은 귀하를 데이터 처리자(Data-processor)의 역할에서 벗어나게 해줍니다. 방문자의 콘텐츠는 소유자가 설정한 제공업체로 직접 전달되며, 귀하는 이를 절대 보유하지 않습니다.