Skip to content
Prego Prego Docs

English {#english}

RAG AI Phase 1 Implementation Plan (Build — Wrangler & Dev)

Purpose: Define stepwise scope, dependencies, and deliverables to implement Phase 1 (Build) from rag-ai-edge-architecture-plan.md. No code generation — implementation order and specification only.

References: RAG AI plan §2 (core components), §3 (Zuplo metering·billing), §4 (Vectorize·D1 provisioning), §6.1 (Phase 1 goals).

1. Implementation order and dependencies

[1] Vectorize·D1 provisioning (Pulumi or dashboard)
         ↓
[2] RAG D1 schema (tenant_ai_settings, usage, etc.)
         ↓
[3] Data Ingestion Worker (R2 → text extract → embed → Vectorize upsert)
         ↓
[4] RAG Query Worker (query → Vectorize → Workers AI → response + token meta)
         ↓
[5] Zuplo Custom Policy (Pre-proc Quota, Post-proc usage + Stripe)
         ↓
[6] Wrangler integration, local/staging deploy
  • [1] required for Vectorize index and D1; [3][4] depend on it. [2] D1 tables used by [3][4][5] for tenant settings, quota, usage. [4] must return token count (header/body) for [5] Post-proc. [5] deployed via Zuplo; Zuplo calls [4] backend.

2. Step deliverables (summary)

  • 2.1 Provisioning: Pulumi or runbook → D1 (prego_hr_master_db), Vectorize (prego-hr-knowledge-base, preset cf-baai-bge-small-en-v1.5), API Token. Outputs: D1_DATABASE_ID, VECTORIZE_INDEX_NAME, Token (secret).
  • 2.2 D1 schema: Migration 0008_rag_ai.sql — tenant_ai_settings, tenant_ai_usage_daily, meters.ai_tokens. Join with tenants_master, plan_entitlements for Quota·Stripe.
  • 2.3 Data Ingestion: Trigger (R2 event or POST /admin/ingest). Pipeline: R2 read → text extract → chunk → Workers AI Embedding → Vectorize upsert (namespace=tenant_id). Wrangler: R2, Vectorize, D1 bindings.
  • 2.4 RAG Query: POST /ai/query (routed by Zuplo). Pipeline: Privacy Masking → embed → Vectorize search (namespace=tenant_id) → Workers AI → response. Return x-ai-usage-tokens (or body) for metering. Skeleton: workers/rag-query/ (wrangler.toml, GET /health, POST /ai/query).
  • 2.5 Zuplo Policy: Inbound — tenant_id, D1 Quota check, 429 if over. Outbound — extract x-ai-usage-tokens, waitUntil: D1 usage upsert, Stripe usage_records (idempotency_key). Ref plan §3.
  • 2.6 Wrangler: workers/rag-ingestion, workers/rag-query (or single Worker routing). Local: wrangler dev. Staging: deploy and verify Zuplo routing.

3. Verification checklist

  • Vectorize index and D1 created (Pulumi or manual); index name and DB ID confirmed.
  • D1 has tenant_ai_settings and usage tables.
  • Test PDF to R2 → Ingestion → vectors in Vectorize for that namespace.
  • /ai/query → Vectorize search → Workers AI response and token header.
  • Zuplo Inbound returns 429 when Quota exceeded.
  • Zuplo Outbound: after response, D1 usage updated and Stripe usage_record (test mode) sent.
  • wrangler dev and staging deploy; full flow works.

4. References

Full tables per step (§2.1–§2.6) are in the Korean section below.

한국어 {#korean}

RAG AI Phase 1 구현 계획 (Build — Wrangler & Dev)

목적: rag-ai-edge-architecture-plan.md Phase 1(Build) 산출물을 구현하기 위한 단계별 범위·의존 관계·산출물 정리. 코드 생성 없음 — 구현 순서·명세만 포함.

참조: RAG AI 기획서 §2(핵심 구성요소), §3(Zuplo 메터링·빌링), §4(Vectorize·D1 프로비저닝), §6.1(Phase 1 목표).

1. 구현 순서 및 의존 관계

[1] Vectorize·D1 프로비저닝 (Pulumi 또는 대시보드)
         ↓
[2] RAG 전용 D1 스키마 확장 (tenant_ai_settings, usage 등)
         ↓
[3] Data Ingestion Worker (R2 업로드 → 텍스트 추출 → 임베딩 → Vectorize upsert)
         ↓
[4] RAG Query Worker (질의 → Vectorize 검색 → Workers AI → 응답, 토큰 메타 반환)
         ↓
[5] Zuplo Custom Policy (Pre-proc Quota 체크, Post-proc 사용량 기록·Stripe)
         ↓
[6] Wrangler 통합·로컬/스테이징 배포
  • [1] 없으면 Vectorize 인덱스·D1 DB가 없어 [3][4] 불가.
  • [2] D1 테이블은 **[3][4][5]**에서 테넌트 설정·쿼터·사용량 저장에 사용.
  • [4] 에서 응답에 토큰 수(헤더/바디)를 포함해야 [5] Post-proc에서 기록 가능.
  • [5] 는 Zuplo 대시보드 또는 Config as Code로 배치; [4] 백엔드 URL을 Zuplo가 호출.

2. 단계별 산출물

2.1 Vectorize·D1 프로비저닝 (순서 1)

산출물내용
Pulumi 스크립트 또는 Runbook고객 Cloudflare Account ID 입력 시 D1 DB(prego_hr_master_db), Vectorize 인덱스(prego-hr-knowledge-base, preset cf-baai-bge-small-en-v1.5), API Token(Workers R2/D1/Scripts 권한) 생성. 기획서 §4 참조.
산출값D1_DATABASE_ID, VECTORIZE_INDEX_NAME, API Token(Secret). Control Plane 또는 Zuplo env에 저장.

2.2 D1 스키마 확장 (순서 2)

산출물내용
마이그레이션0008_rag_ai.sql 적용. tenant_ai_settings(tenant_id, vectorize_namespace, quota_daily, quota_monthly, stripe_subscription_item_id), tenant_ai_usage_daily(tenant_id, dt, tokens_used) — Zuplo Policy에서 Quota 조회·사용량 upsert. meters에 ai_tokens 등록(기존 usage_rollups 연동용).
연동기존 tenants_master, plan_entitlements와 조인하여 플랜별 Quota·Stripe subscription_item_id 매핑.

2.3 Data Ingestion Worker (순서 3)

산출물내용
트리거R2에 문서 업로드 시(Event Notifications 또는 수동 API 호출). 또는 관리자 API POST /admin/ingest 로 버킷 경로 지정.
파이프라인① R2에서 객체 읽기(PDF/Office 등) ② Workers에서 텍스트 추출(라이브러리 또는 Workers AI 문서 이해 API) ③ 청크 분할 ④ Workers AI Embedding으로 벡터화 ⑤ Vectorize에 upsert(namespace=tenant_id).
설정Wrangler에 R2 버킷·Vectorize·D1 바인딩. tenant_id는 요청 헤더 또는 R2 key prefix에서 추출.

2.4 RAG Query Worker (순서 4)

산출물내용
엔드포인트POST /ai/query (Zuplo가 라우팅). Body: 질의 텍스트, (선택) namespace/document_set.
파이프라인① Privacy Masking(질의 내 NRIC/FIN 등 마스킹) ② 질의 임베딩 ③ Vectorize 유사도 검색(namespace=tenant_id) ④ 상위 K개 청크 + 질의로 Workers AI(Llama/Mistral) 호출 ⑤ 응답 생성.
응답 메타Workers AI 응답과 함께 사용 토큰 수를 응답 헤더(예: x-ai-usage-tokens) 또는 JSON body 필드로 반환. Zuplo Post-proc에서 이 값을 읽어 메터링.
설정Wrangler에 Vectorize·D1·Workers AI 바인딩. 스켈레톤: workers/rag-query/ (wrangler.toml, src/index.ts 스텁, GET /health, POST /ai/query + x-ai-usage-tokens).

2.5 Zuplo Custom Policy — 메터링 (순서 5)

산출물내용
Inbound테넌트 식별(API Key → tenant_id). D1에서 남은 Quota 조회. 초과 시 429 반환.
Outboundnext() 호출 후 응답에서 x-ai-usage-tokens(또는 동일 스펙) 추출. waitUntil(또는 동등)으로 비동기: D1 사용량 누적, Stripe subscription_items/.../usage_records 전송(idempotency_key 포함). 기획서 §3 참조.
환경D1 접근, Stripe Secret Key, Subscription Item ID 매핑(테넌트/플랜별).

2.6 Wrangler 통합·배포 (순서 6)

산출물내용
구성Data Ingestion Worker·RAG Query Worker를 각각 workers/rag-ingestion, workers/rag-query 등으로 Wrangler 프로젝트 구성. 또는 단일 Worker에서 라우팅.
로컬wrangler dev 로 Workers AI·Vectorize·D1·R2 로컬 테스트.
스테이징스테이징 환경에 배포 후 Zuplo에서 스테이징 백엔드 URL로 라우팅 검증.

3. 검증 체크리스트

  • Pulumi(또는 수동)로 Vectorize 인덱스·D1 생성 후 인덱스 이름·DB ID 확인.
  • D1에 tenant_ai_settings·ai_usage(또는 동일 목적) 테이블 존재.
  • R2에 테스트 PDF 업로드 → Ingestion Worker 실행 → Vectorize 해당 namespace에 벡터 존재.
  • /ai/query 호출 시 Vectorize 검색 → Workers AI 응답·토큰 수 헤더 반환.
  • Zuplo Inbound에서 Quota 초과 시 429 반환.
  • Zuplo Outbound에서 응답 후 D1 사용량 증가·Stripe usage_record(테스트 모드) 전송 확인.
  • wrangler dev 및 스테이징 배포로 전체 플로우 동작.

4. 참조

Help