English {#english}
Worker AI Implementation Plan
Purpose : Define scope, requirements, and architecture for Edge-Native Worker AI to build and use Prego’s core knowledge base. No code generation — planning and specification only.
Document version : 1.0
References : rag-ai-edge-architecture-plan.md , rag-ai-phase1-implementation-plan.md , zuplo-ai-metering-policy.md .
Contents : §1 Purpose·scope · §2 Assumptions·refs · §3 Architecture · §4 Module requirements · §5 UI/UX · §6 Security·compliance · §7 Deployment · §8 Implementation order·Phase · §9 Verification · §10 Open items · §11 API · §12 D1·Vectorize schema · §13 Limits·errors · §14 PDF extraction · §15 Streaming · §16 Tenant·onboarding · §17 Monitoring · §18 Glossary · §19 Related plans.
Recommended reading order for implementation : §8 → §11 → §12 → §4 → §7. Before deploy: §9 verification, §13 limits, §13.1 edge constraints.
1. Purpose and Scope
1.1 Purpose
Edge-Native Data Ingestion : PDF (and similar) upload → text extraction → chunking → embedding → Vectorize storage, all on the Cloudflare edge .RAG Query : User question → embedding → Vectorize similarity search (tenant-isolated) → context augmentation → Workers AI answer.Compliance Checker : Cross-check central (MOM) statutory knowledge and tenant company policy → CRITICAL / WARNING / COMPLIANT.PII protection : NRIC/FIN etc. masked at the edge, inbound (before AI) and outbound (before client).UI/UX : Context-aware AI chat, source attribution, streaming responses, chat history with auto-deletion policy.
1.2 Scope
In scope Out of scope Requirements, interfaces, pipeline spec for Data Ingestion, RAG Query, Compliance Checker, PII FilterActual TypeScript/code Vectorize, D1, R2, Workers AI bindings and deployment layout Pulumi scripts (see RAG Phase1·architecture) Zuplo gateway, metering, PII strategy Zuplo Config as Code detail Security·compliance (PDPA, tenant isolation) principles Audit log schema detail
2. Assumptions and References
3. Architecture Overview
3.1 Data Ingestion Pipeline
[Client] PDF upload (Multipart Form)
[Worker] R2 temp store (audit/reprocess, tenant prefix)
[Worker] Text extraction (edge: WASM-compatible PDF lib)
[Worker] Chunking (e.g. 512 tokens, dedup/whitespace trim)
[Worker] Workers AI embedding (same model: bge-small-en-v1.5)
[Vectorize] upsert (id, values, metadata: tenantId, source, content, page)
[Worker] Delete R2 temp object when done (PDPA retention)
3.2 RAG Query Pipeline
[Client] POST { question } + x-tenant-id
[Worker] (optional) PII Inbound filter
[Worker] Question embedding (same model as Ingestion)
[Vectorize] query(vector, topK, filter: { tenantId }, returnMetadata: true)
[Worker] Assemble context (top K chunks + source metadata)
[Workers AI] System prompt + Context + Question → answer (anti-hallucination)
[Worker] (optional) PII Outbound filter
[Response] answer + sources, x-ai-usage-tokens (for Zuplo metering)
3.3 Compliance Checker Pipeline
Client POST { topic, tenantId } → Vectorize global-statutory + tenant filter → Workers AI comparison → CRITICAL / WARNING / COMPLIANT + rationale.
3.4 PII Filter Placement
Inbound : Mask NRIC/FIN etc. immediately before question reaches Workers AI / RAG.Outbound : Mask again immediately before AI response goes to client.Zero-Log : Original (pre-mask) only in memory; not logged.Extension : Zuplo Outbound Policy for full response scan, DLP, de-identified audit logs.
4. Module Requirements (Summary)
Data Ingestion : Multipart PDF, x-tenant-id required; R2 temp path by tenant; WASM PDF extraction; chunking (e.g. 512 tokens); Workers AI embedding; Vectorize upsert with tenantId/source/content/page; delete R2 temp on success.RAG Query : JSON { question }, x-tenant-id; always filter: { tenantId } on Vectorize; topK 3–5; system prompt for context-only answers and no hallucination; response: answer, sources, x-ai-usage-tokens.Compliance Checker : JSON { topic, tenantId }; Vectorize global-statutory + tenant filter; Workers AI → CRITICAL/WARNING/COMPLIANT + reason.PII Filter : NRIC/FIN with regex + checksum; Inbound + Outbound; fixed mask token; Zero-Log; optional Zuplo Guardrail.
5. UI/UX
Prego AI Assistant : Context-aware (e.g. “my leave balance” + employee + policy); source transparency; streaming (typing effect); chat history in D1, 7-day auto-deletion.Onboarding : Expose AI assistant at end of onboarding; Compliance results (CRITICAL/WARNING) in admin only.
6. Security and Compliance
Tenant isolation : Every Vectorize query uses filter: { tenantId }; R2 paths with tenantId prefix; Worker-only access.PDPA : R2 temp files deleted after processing; chat retention then auto-delete; PII edge-only, Zero-Log.Zuplo : PII Outbound Policy; API metering (tokens → Stripe usage_record).Cost : Chunk dedup, topK 3–5, R2 temp delete, x-ai-usage-tokens for accurate billing.
7. Deployment and Infra
Layout : e.g. workers/rag-ingestion, rag-query, compliance-checker, shared PII util; wrangler.toml with AI, VECTORIZE, D1, R2_BUCKET, vars/secrets.Deploy order : (1) Pulumi D1·Vectorize·R2·token → wrangler; (2) D1 migrations; (3) Ingest global-statutory; (4) Workers Ingestion → Query → Compliance → PII; (5) Zuplo policies and upstreams; (6) Frontend + streaming.
8. Implementation Order and Phase
Phase Content Deps P0 Vectorize·D1·R2 provisioning, wrangler bindings — P1 Data Ingestion (PDF → text → chunk → embed → Vectorize), R2 temp store·delete P0 P2 RAG Query (question → embed → Vectorize + tenant filter → LLM → response), sources·tokens P0, P1 P3 PII Filter Inbound/Outbound, NRIC/FIN checksum·mask, Zero-Log P2 P4 Compliance Checker (global-statutory + tenant cross-check) P0, P1 P5 Zuplo metering·PII Outbound, Stripe usage_record P2, P3 P6 UI: AI chat, context-aware, sources, streaming, history D1·7-day delete P2, P5
§§9–19 (verification checklist, open items, API summary, D1·Vectorize schema, limits·errors, PDF extraction options, streaming format, tenant·onboarding, monitoring, glossary, related plans) — full tables, API contract, schema, edge limits, and retry policy are in the Korean section below.
한국어 {#korean}
Worker AI 구현 기획서
목적 : Prego의 핵심 지식 기반을 구축·활용하기 위한 Edge-Native Worker AI 구현 범위·요구사항·아키텍처를 정의한다. 코드 생성 없음 — 기획·명세만 포함.
문서 버전 : 1.0
참조 : rag-ai-edge-architecture-plan.md , rag-ai-phase1-implementation-plan.md , zuplo-ai-metering-policy.md .
문서 목차 : §1 목적·범위 · §2 전제·참조 · §3 아키텍처 개요 · §4 모듈별 요구사항 · §5 UI/UX · §6 보안·컴플라이언스 · §7 배포·인프라 · §8 구현 순서·Phase · §9 검증 체크리스트 · §10 미결정 · §11 API 인터페이스 · §12 D1·Vectorize 스키마 · §13 제한·에러 · §14 PDF 추출 옵션 · §15 스트리밍·응답 · §16 테넌트·온보딩 연동 · §17 모니터링·운영 · §18 용어·약어 · §19 관련 기획서.
구현 시 권장 읽기 순서 : §8(Phase·산출물) → §11(API) → §12(스키마) → §4(모듈 요구사항) → §7(배포). 배포 전 §9 검증·§13 제한·§13.1 에지 제약 확인.
1. 목적·범위
1.1 목적
Edge-Native Data Ingestion : PDF 등 문서 업로드 → 텍스트 추출 → 청킹 → 임베딩 → Vectorize 저장을 Cloudflare 엣지 에서 일괄 처리.RAG Query : 사용자 질문 → 임베딩 → Vectorize 유사도 검색(테넌트 격리) → 문맥 증강 → Workers AI 답변 생성.Compliance Checker : 중앙 법령(MOM) 지식과 테넌트 사내 규정을 교차 분석하여 위반/주의/준수 판정.PII 보호 : 질문·답변 경로에서 NRIC/FIN 등 개인식별정보를 엣지에서 이중(Inbound/Outbound) 마스킹.UI/UX : Context-Aware AI 채팅, 출처 표시, 스트리밍 응답, 채팅 이력 보관·자동 파기 정책.
1.2 범위
포함 제외(별도 기획) Data Ingestion Worker, RAG Query Worker, Compliance Checker, PII Filter의 요구사항·인터페이스·파이프라인 명세 실제 TypeScript/코드 구현 Vectorize·D1·R2·Workers AI 바인딩 및 배포 구조 Pulumi 상세 스크립트(기존 RAG Phase1·아키텍처 문서 참조) Zuplo 게이트웨이·메터링·PII 연동 전략 Zuplo Config as Code 상세 보안·컴플라이언스(PDPA, 테넌트 격리) 원칙 감사 로그 스키마 상세
2. 전제·참조 문서
3. 아키텍처 개요
3.1 Data Ingestion 파이프라인
[클라이언트] PDF 업로드 (Multipart Form)
[Worker] R2 임시 저장 (감사·재처리용, tenant prefix)
[Worker] 텍스트 추출 (엣지 가능: WASM 기반 PDF 라이브러리)
[Worker] 청킹 (예: 512 토큰 단위, 중복/공백 정리로 비용 절감)
[Worker] Workers AI 임베딩 (동일 모델: bge-small-en-v1.5)
[Vectorize] upsert (id, values, metadata: tenantId, source, content, page)
[Worker] 완료 후 R2 임시 객체 파기 (PDPA 보관 제한)
3.2 RAG Query 파이프라인
[클라이언트] POST { question } + x-tenant-id
[Worker] (선택) PII Inbound 필터
[Worker] 질문 임베딩 (Ingestion과 동일 모델)
[Vectorize] query(vector, topK, filter: { tenantId }, returnMetadata: true)
[Worker] Context 조립 (상위 K개 청크, 출처 메타 포함)
[Workers AI] 시스템 프롬프트 + Context + Question → 답변 (할루시네이션 방지 지침)
[Worker] (선택) PII Outbound 필터
[응답] answer + sources (출처 목록), x-ai-usage-tokens (Zuplo 메터링용)
3.3 Compliance Checker 파이프라인
[클라이언트] POST { topic, tenantId }
[Vectorize] 중앙 법령(MOM) 검색 (namespace: global-statutory, topK)
[Vectorize] 테넌트 사내 규정 검색 (filter: { tenantId }, topK)
[Workers AI] 두 문맥 비교 → CRITICAL / WARNING / COMPLIANT + 이유
3.4 PII Filter 위치
Inbound : 사용자 질문이 Workers AI·RAG 검색으로 넘어가기 직전 에 NRIC/FIN 등 마스킹.Outbound : AI 생성 답변이 클라이언트로 나가기 직전 에 한 번 더 마스킹.Zero-Log : 마스킹 전 원본은 메모리에서만 처리, 로그에는 남기지 않음.확장 : Zuplo Outbound Policy로 응답 전수 검사·DLP·비식별 감사 로그 가능.
4. 모듈별 요구사항
4.1 Data Ingestion Worker
항목 요구사항 트리거 Multipart Form으로 PDF 업로드. x-tenant-id 헤더 필수. 저장 원본을 R2 temp/{tenantId}/{timestamp}-{filename}에 임시 저장 후, 처리 완료 시 삭제(PDPA). 텍스트 추출 WASM 호환 PDF 라이브러리 사용. Node 전용 라이브러리는 Worker 미지원.메모리 Worker 메모리 제한(예: 128MB) 고려. 대용량 PDF는 스트리밍 또는 세그먼트 단위 처리 검토. 청킹 고정 토큰 수(예: 512) 또는 문자 수 단위. 중복·과도한 공백 제거로 임베딩 비용 최소화. 임베딩 Workers AI @cf/baai/bge-small-en-v1.5. Ingestion·Query 동일 모델 유지. Vectorize upsert 시 metadata: tenantId, source(파일명), content(청크 원문), page(또는 chunk index). 검색 시 tenantId 필터 필수. 응답 success, chunks 개수, 임시 파일 파기 완료 메시지.
4.2 RAG Query Worker
항목 요구사항 입력 JSON body { question }, 헤더 x-tenant-id. 테넌트 격리 VECTORIZE.query 시 반드시 filter: { tenantId } 적용. 타 테넌트 데이터 유출 금지.Top-K 3~5개 청크 권장. 과다 시 토큰 비용·혼동 증가. 시스템 프롬프트 Context 기반 답변, Context에 없으면 “해당 정보를 찾을 수 없습니다” 응답, 할루시네이션 금지 명시. 출처 응답에 sources(문서명·페이지 등) 포함해 사용자가 검증 가능하도록. 메터링 응답에 x-ai-usage-tokens(또는 동일 스펙) 포함. Zuplo Post-proc에서 D1·Stripe 연동.
4.3 Compliance Checker
항목 요구사항 입력 JSON { topic, tenantId }. 주제(예: 연차, 초과수당)와 테넌트. 지식 소스 (1) Vectorize global-statutory namespace — 중앙 MOM 법령. (2) Vectorize tenant filter — 해당 테넌트 사내 규정. 분석 Workers AI에 두 문맥 전달, “위반/주의/준수” 판정 및 이유 생성. 출력: CRITICAL / WARNING / COMPLIANT. 역할 온보딩·정책 등록 시 실시간 검증, 엔터프라이즈 HR 법적 리스크 관리 셀링 포인트.
4.4 Edge-side PII Filter
항목 요구사항 대상 NRIC/FIN 등 싱가포르 개인식별정보. 정규식 + 체크섬 검증 으로 유효 번호만 마스킹(오탐 감소). 위치 Inbound(질문), Outbound(답변). AI 요청/응답 경로 양단. 형식 마스킹 시 [CONFIDENTIAL_ID_MASKED] 또는 [REDACTED_NRIC] 등 고정 토큰으로 치환. 시스템 지침 LLM 프롬프트에 “실명·NRIC를 답변에 포함하지 마라” 지침 추가해 필터와 상호보완. PDPA 보호 의무 이행 근거로 정책·감사에 활용.
5. UI/UX 요구사항
5.1 Prego AI Assistant (채팅)
항목 요구사항 Context-Aware ”내 연차는 몇 일이야?” 등 질문 시, 이미 알고 있는 직원 정보(입사일 등)와 사내 규정을 결합해 개인화 답변 . Source Transparency 답변 하단에 “출처: 사내 복지 규정 제4조” 등 표기. 신뢰도·검증 가능성. Streaming Workers AI 스트리밍 응답으로 한 글자씩 타이핑 효과(UX). 스택 제안 Frontend: React + Tailwind. 채팅 이력: D1 저장, 7일 후 자동 파기 정책.
5.2 온보딩 연동
온보딩 마지막 단계에서 신규 입사자 대상 AI 비서 노출.
Compliance Checker 결과(CRITICAL/WARNING)는 관리자 대시에서만 노출하는 등 권한 분리.
6. 보안·컴플라이언스
6.1 테넌트 격리
Vectorize: 모든 query에 filter: { tenantId } 적용. namespace 또는 metadata 필터로 타 테넌트 미접근.
R2: 경로에 tenantId prefix. Worker만 접근, 클라이언트 직접 접근 없음.
6.2 PDPA·데이터 최소화
R2 임시 파일: 처리 완료 후 즉시 삭제.
채팅 이력: 보관 기간(예: 7일) 후 자동 파기.
PII: 엣지에서만 처리, 로그 비저장(Zero-Log).
6.3 Zuplo 연동
PII Filter : 게이트웨이 Outbound Policy로 응답 전수 검사·마스킹·비식별 감사 로그.API Metering : Query 1회당 토큰량 측정 → Stripe usage_record 전송.
6.4 비용·최적화 원칙
Ingestion : 청킹 시 중복·과도한 공백 제거로 임베딩 토큰 최소화. 동일 문서 재업로드 시 기존 벡터 덮어쓰기(id 정책)로 중복 축적 방지.Query : topK 3~5 유지, Context 길이 제한으로 LLM 토큰 비용·지연 제어.R2 : 임시 파일 처리 완료 후 즉시 삭제해 저장 비용·PDPA 준수.메터링 : x-ai-usage-tokens로 실제 사용량만 Stripe에 전송해 과금 정확도 유지.
7. 배포·인프라
7.1 폴더 구조 (참조)
├── app/ # Cloudflare Pages (Frontend + API Functions)
│ ├── src/ # React UI (온보딩 위저드, AI 채팅)
│ └── functions/ # API (D1, Stripe Webhook, RAG Query 등)
├── workers/ # 전용 Worker 진입점 (또는 app/functions 내 라우팅)
│ ├── rag-ingestion/ # Data Ingestion
│ ├── rag-query/ # RAG Query
│ ├── compliance-checker/ # Compliance Checker
│ └── (공통) pii-filter # 유틸 또는 미들웨어
├── wrangler.toml # AI, Vectorize, D1, R2 바인딩
7.2 Wrangler 바인딩 (요약)
바인딩 용도 AI Workers AI (임베딩, Llama 등). VECTORIZE prego-hr-knowledge-base (또는 Pulumi에서 생성한 인덱스). D1 prego_hr_master_db (테넌트·설정·사용량·채팅 메타). R2_BUCKET 임시 업로드·원본 보관(경로 정책에 따라). vars STRIPE_WEBHOOK_SECRET, ZUPLO_API_URL 등(비밀은 Secret).
7.3 배포 순서(권장)
인프라: Pulumi로 D1·Vectorize·R2·API Token 생성 → wrangler.toml 반영.
D1: RAG·테넌트 AI 설정·사용량·채팅 테이블 마이그레이션.
지식 베이스: 중앙 MOM 데이터를 global-statutory namespace에 Ingestion.
Workers: Ingestion → Query → Compliance Checker → PII 유틸 순 구현·배포.
Zuplo: PII Policy·Metering Policy 활성화, Worker URL 업스트림 등록.
Frontend: Pages 배포, AI 채팅 컴포넌트·스트리밍 연동.
8. 구현 순서·Phase
Phase 내용 의존 P0 Vectorize·D1·R2 프로비저닝, wrangler 바인딩 — P1 Data Ingestion Worker (PDF → 텍스트 → 청킹 → 임베딩 → Vectorize), R2 임시 저장·파기 P0 P2 RAG Query Worker (질문 → 임베딩 → Vectorize query + tenant filter → LLM → 응답), sources·토큰 메타 P0, P1 P3 PII Filter (Inbound/Outbound), NRIC/FIN 체크섬·마스킹, Zero-Log P2 P4 Compliance Checker (global-statutory + tenant 규정 교차 분석) P0, P1 P5 Zuplo 메터링·PII Outbound Policy, Stripe usage_record P2, P3 P6 UI: AI 채팅 컴포넌트, Context-Aware, 출처 표시, 스트리밍, 이력 D1·7일 파기 P2, P5
8.1 Phase별 산출물 요약
Phase 산출물·엔드포인트 비고 P0 Vectorize 인덱스, D1 DB, R2 버킷, wrangler 바인딩 Pulumi 또는 대시보드, 인덱스 이름·DB ID 확정 P1 POST Ingestion API, R2 temp 경로, Vectorize upsert(tenantId 메타) PDF → 청킹 → 임베딩 → 저장, R2 임시 삭제 P2 POST RAG Query API, answer·sources, x-ai-usage-tokens Vectorize filter: tenantId, Workers AI LLM P3 PII 마스킹 유틸, Inbound(질문)·Outbound(답변) 적용 NRIC/FIN 체크섬·Zero-Log P4 POST Compliance Checker API, analysis (CRITICAL/WARNING/COMPLIANT) global-statutory + tenant 규정 교차 분석 P5 Zuplo Quota Inbound, 사용량 Outbound, Stripe usage_record D1 tenant_ai_usage_daily, PII Outbound Policy P6 AI 채팅 UI, 스트리밍 답변, 출처 표시, chat_history D1·7일 파기 Context-Aware, 플랜별 노출
9. 검증 체크리스트
9.1 테스트 전략 요약
수준 대상 요점 단위 청킹 유틸, PII 마스킹 함수 경계·공백·NRIC 패턴·체크섬, 오탐 없음. 통합 Vectorize query + filter tenantId 필터 시 타 테넌트 벡터 미반환, returnMetadata 검증. 통합 Ingestion → Vectorize upsert R2 저장·삭제, 메타데이터(tenantId, source, content) 일치. E2E Ingestion → Query → 답변 PDF 업로드 후 동일 tenant로 질의 시 해당 문서 출처 포함. 보안 테넌트 격리 A tenant로 upsert한 벡터를 B tenant query에서 조회 불가. 보안 PII 질문/답변에 NRIC 포함 시 마스킹된 값만 로그·AI 입력에 노출.
10. 미결정·후속 검토
항목 설명 PDF 라이브러리 WASM 호환 PDF 텍스트 추출 라이브러리 선정(예: pdf-parse WASM 포트, Cloudflare 문서 이해 API 등). 대용량 PDF 단일 Worker 실행 시간·메모리 제한 내에서 처리할 수 있는 페이지 수 상한, 초과 시 큐·청크 단위 비동기 처리 여부. Vectorize namespace 단일 인덱스 + metadata filter vs namespace(tenant_id) 사용 방식 최종 결정(기존 RAG 기획서와 정합성). Compliance 인덱스 global-statutory 인덱스/네임스페이스 구축 주체(Prego 운영팀 vs 고객별)·업데이트 주기. 채팅 이력 스키마 D1 테이블 설계(tenant_id, user_id, message role/content, created_at, ttl 또는 삭제 job). 다국어 지원 언어(영어·중국어 등), 다국어 임베딩 모델(bge 다국어 버전 등) 선정 및 Query/Ingestion 동일 모델 유지.
11. API 인터페이스 요약
엔드포인트 메서드 요청 응답·헤더 비고 Ingestion POST Multipart: file(PDF), 헤더 x-tenant-id 200: { success, chunks, message } / 400: Missing Tenant ID, No file / 500: Ingestion failed Zuplo 인증·Quota 적용 RAG Query POST JSON { question }, 헤더 x-tenant-id 200: { answer, sources }, 헤더 x-ai-usage-tokens / 400: Invalid request / 500: AI Processing Error Zuplo 메터링이 토큰 수 수집 Compliance Checker POST JSON { topic, tenantId } 200: { analysis } (CRITICAL/WARNING/COMPLIANT + 이유) / 400, 500 관리자 또는 온보딩 플로우
모든 API는 Zuplo 게이트웨이 뒤에 배치하며, 테넌트 식별은 API Key → tenant_id 매핑으로 수행.
12. D1·Vectorize 스키마 요약
12.1 D1 (참조: RAG Phase1·기존 마이그레이션)
테이블 용도 주요 필드(예) tenant_ai_settings 테넌트별 RAG·Quota 설정 tenant_id, vectorize_namespace(또는 filter용 tenantId), quota_daily, quota_monthly, stripe_subscription_item_id tenant_ai_usage_daily 일별 AI 사용량 tenant_id, dt, tokens_used (Zuplo Post-proc에서 upsert) chat_history (미결정)채팅 이력·7일 파기 tenant_id, user_id, role(user/assistant), content, created_at. TTL 또는 Cron 삭제 job.
12.2 Vectorize 인덱스
항목 내용 Preset cf-baai-bge-small-en-v1.5 (Ingestion·Query 동일).Metadata tenantId(필수), source(파일명), content(청크 원문), page 또는 chunk_index. Compliance용 global-statutory는 namespace 또는 metadata로 구분. 격리 쿼리 시 반드시 filter: { tenantId } 또는 namespace 지정.
13. 제한·에러 처리
구분 정책 응답 Ingestion 파일 크기 상한(예: 10MB), 허용 MIME: application/pdf. 초과·비허용 시 400. 400: No file / File too large / Unsupported type Ingestion Worker CPU/메모리·실행 시간 초과 시 500, 클라이언트 재시도 또는 청크 단위 비동기 설계 검토. 500: Ingestion failed Query Zuplo에서 일/월 Quota 초과 시 429. 429: Quota exceeded Query question 누락·tenantId 누락 시 400. 400: Invalid request Compliance topic·tenantId 누락 시 400. 400 공통 AI·Vectorize·D1 일시 오류 시 500, 재시도 가능 메시지. 500: AI Processing Error 등
13.1 에지 제약·한도 요약
구현 시 Cloudflare 제품 한도를 고려해 설계·폴백을 두는 것이 좋다. (수치는 공식 문서 기준으로 배포 전 재확인.)
구분 항목 참고 Worker CPU 시간·메모리(예: 128MB)·실행 시간 상한 대용량 PDF는 세그먼트/스트리밍 또는 청크 단위 비동기 처리 검토. Vectorize 인덱스당 벡터 수·차원 수·메타데이터 크기 preset bge-small-en-v1.5 차원과 동일한 인덱스 생성. Workers AI 요청당 토큰 한도·동시 호출 스트리밍·배치 크기 조절로 초과 방지. R2 업로드 객체 크기·요청 한도 Ingestion 파일 크기 상한(§13)과 연동. D1 행 수·쿼리 시간·바인딩 수 tenant_ai_usage_daily 등 집계 테이블 주기 정리·인덱스 설계.
13.2 클라이언트 재시도·Ingestion 실패 시 정책
429(Quota) / 503·500(일시 오류) : 클라이언트는 exponential backoff로 재시도. 429는 Quota 갱신 전까지 재시도해도 동일 응답 가능.Ingestion 500 : Worker 내부에서 예외 발생 시, R2 임시 파일을 유지 할지 즉시 삭제 할지 정책 결정. 유지 시 같은 키로 재요청 시 재처리 가능; 삭제 시 PDPA·용량 우선. 구현 시 try/finally에서 성공 시에만 삭제하는 패턴 권장.
14. PDF·텍스트 추출 옵션
옵션 설명 비고 Workers AI 문서 이해 Cloudflare Workers AI에 문서 이해 API가 있는 경우, 엣지에서 PDF → 텍스트 호출. 공식 지원 여부·한도 확인 필요. 엣지 네이티브, Node 의존 없음. WASM PDF 라이브러리 pdf.js(Mozilla), pdf-parse의 WASM 포트 등 Worker 호환 빌드. Worker 런타임에서 import 가능한지 검증 필요. 메모리·실행 시간 제한 내에서 페이지 수 상한 결정. 외부 서비스 PDF 추출만 별도 서비스(Lambda·전용 API)로 두고, Worker는 텍스트 수신 후 청킹·임베딩만 수행. 엣지 풀 스택에서 벗어남, 보안·지연 고려.
구현 Phase에서 WASM 호환 여부·벤치마크 후 선정 권장.
15. 스트리밍·응답 형식
항목 요구사항 프로토콜 Workers AI 스트리밍 응답을 클라이언트에 전달할 방식(SSE, ReadableStream 등) 결정. Zuplo가 스트리밍을 그대로 프록시하는지 확인. 토큰 단위 답변을 한 글자/토큰 단위로 전송해 UI에서 타이핑 효과 구현. 최종 토큰 수는 스트림 종료 후 헤더 또는 마지막 이벤트로 전달해 메터링에 사용. 에러 스트리밍 중 AI/네트워크 오류 시 클라이언트가 부분 응답·에러 구분 가능하도록 이벤트 형식 정의. 출처 스트리밍이 끝난 뒤 sources 배열을 한 번에 반환하거나, 스트림 메타 이벤트로 전달.
16. 테넌트·온보딩 연동
항목 요구사항 테넌트 프로비저닝 신규 테넌트 생성 시 D1 tenant_ai_settings 초기화(quota, stripe_subscription_item_id). Vectorize는 단일 인덱스 + metadata tenantId로 격리하므로 별도 리소스 생성 불필요. AI 활성화 조건 플랜별로 RAG AI 사용 여부·일/월 Quota 차등. 온보딩 완료 또는 첫 로그인 시 AI 채팅 노출 여부는 tenant_ai_settings·플랜 조인으로 판단. 온보딩 플로우 마지막 단계에서 Prego AI Assistant 진입. 필요 시 Compliance Checker 결과(CRITICAL/WARNING)는 관리자 화면에서만 노출. 지식 베이스 초기화 테넌트별로 사내 규정 PDF를 업로드·Ingestion 호출. 중앙 MOM 데이터(global-statutory)는 운영팀이 사전 Ingestion.
17. 모니터링·운영
항목 요구사항 로그 Worker 내부 로그는 비식별화(tenant_id는 가능, PII·원문 미포함). Cloudflare Workers Analytics·Logpush 연동 검토. 알림 Ingestion 실패율 상승, Quota 임계 도달(예: 80%), Vectorize/D1 오류율 증가 시 알림 채널(Slack·이메일) 연동. 메터링 검증 Zuplo → D1 usage 누적·Stripe usage_record 전송이 주기적으로 일치하는지 대시보드 또는 수동 검증. 용량 Vectorize 인덱스 크기·R2 버킷 용량·D1 행 수 모니터링, 플랜별 상한과 연동.
18. 용어·약어
용어 설명 RAG Retrieval-Augmented Generation. 검색(벡터 유사도)으로 문맥을 가져와 LLM 답변을 보강하는 방식. Vectorize Cloudflare 벡터 인덱스 서비스. 임베딩 벡터 저장·유사도 검색, 메타데이터 필터·namespace 지원. PDPA Personal Data Protection Act. 싱가포르 개인정보보호법. 보관 제한·동의·파기 의무 등. MOM Ministry of Manpower. 싱가포르 노동부. 노동법·법령 지식 베이스(global-statutory)의 출처. NRIC/FIN National Registration Identity Card / Foreign Identification Number. 싱가포르 개인식별번호. PII 필터 대상. PII Personally Identifiable Information. 개인식별정보. topK 벡터 검색 시 가져올 유사도 상위 K개 문서(청크). 보통 3~5. namespace Vectorize 내 논리 구분. 단일 인덱스에서 tenant_id 또는 global-statutory 등으로 격리. Ingestion 문서 업로드 → 텍스트 추출 → 청킹 → 임베딩 → Vectorize 저장까지의 파이프라인. WASM WebAssembly. Worker 런타임에서 Node 전용 라이브러리 대신 사용하는 PDF 등 처리용.
19. 관련 기획서
