지식 베이스 (Knowledge / RAG) - 문서

지식 베이스 (Knowledge Base / RAG)

cb.knowledge 는 문서를 청크 단위로 저장하고 BM25 풀텍스트 검색으로 관련 청크를 찾는 RAG 인프라입니다. 한국어는 nori 형태소 분석기 가 적용되어 "환불은", "환불을" 같이 조사가 붙은 자연어 질의도 정상 매칭됩니다. AI 채팅에 컨텍스트로 연결하려면 cb.ai.chatStream({ knowledgeBaseId }) 를 사용합니다.

사전 준비: 콘솔 > 지식베이스에서 새 KB 를 먼저 생성하세요. chunk_size (100~~2000 토큰, 기본 500) / chunk_overlap (0~~500, 기본 50) / search_top_k (1~50, 기본 5) 설정. KB 생성/삭제는 콘솔/관리자 전용 — SDK Public Key 인증 미노출.

문서 추가

typescript

import { ConnectBase } from 'connectbase-client'

const cb = new ConnectBase({ publicKey: 'cb_pk_YOUR_PUBLIC_KEY' })

// 텍스트 직접 입력
const doc = await cb.knowledge.addDocument('kb-id', {
    name: '환불 정책',
    source_type: 'text',
    content: '환불은 구매 후 7일 이내 신청 가능합니다...',
    metadata: { category: 'policy', version: '2026-05' },
})
// doc.status: 'pending' → 백그라운드 처리 후 'ready'

// URL 에서 가져오기
await cb.knowledge.addDocument('kb-id', {
    name: '도움말',
    source_type: 'url',
    source_url: 'https://example.com/help.html',
})

PDF / DOCX / text 파일 업로드 (SDK 3.17.0+)

addDocumentFromFile 헬퍼는 브라우저 File / Blob 또는 Node Buffer / Uint8Array 를 그대로 받아 base64 인코딩 + MIME 추출까지 자동 처리합니다.

typescript

// 브라우저: <input type="file"> 결과를 그대로
const file = (document.querySelector('input[type=file]') as HTMLInputElement).files![0]
await cb.knowledge.addDocumentFromFile('kb-id', file, {
    metadata: { tag: 'manual' },
})

// Node.js: fs.readFileSync 로 읽은 Buffer
import { readFileSync } from 'node:fs'
await cb.knowledge.addDocumentFromFile('kb-id', {
    data: readFileSync('./report.pdf'),
    mimeType: 'application/pdf',
    name: 'report.pdf',
})

지원 / 미지원 MIME

지원	미지원 (`unsupported mime type for text extraction` 에러)
`application/pdf` (텍스트 PDF)	스캔 이미지 PDF / 이미지 OCR
DOCX (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`)	HWP / XLSX
`text/*` (plain / markdown / csv / html)	기타 바이너리
`application/json`

크기 상한: 50MB (원본 바이너리)
추출 결과 빈 텍스트 → extracted text is empty (스캔 PDF 등)
50MB 초과 → file too large for extraction

문서 처리 완료 대기 (폴링)

typescript

async function waitReady(kbID: string, docID: string, timeoutMs = 60000) {
    const start = Date.now()
    while (Date.now() - start < timeoutMs) {
        const { documents } = await cb.knowledge.listDocuments(kbID)
        const target = documents.find(d => d.id === docID)
        if (target?.status === 'ready') return
        if (target?.status === 'failed') throw new Error(target.error_message ?? '처리 실패')
        await new Promise(r => setTimeout(r, 2000))
    }
    throw new Error('timeout')
}

검색

typescript

// 키워드 검색 (BM25)
const results = await cb.knowledge.search('kb-id', {
    query: '환불 정책이 어떻게 되나요?',
    top_k: 5,
})
results.results.forEach(r => {
    console.log(`[${r.score.toFixed(2)}] ${r.document_name}: ${r.content.slice(0, 80)}...`)
})

// Agentic Search — AI 가 다중 쿼리 자동 생성 (앱에 AI 프로바이더 필요)
await cb.knowledge.search('kb-id', { query: '회원 등급별 혜택 비교', agentic: true })

// GET 방식 (간단한 사용)
await cb.knowledge.searchGet('kb-id', '환불', 3)

사용자별 격리 (다중 사용자 RAG)

Authorization: Bearer <appmember-jwt> 를 함께 보내면 서버가 자동으로 본인 metadata.user_id 로 결과를 제한하고, addDocument 시에도 자동 태깅합니다. search 의 where 에 AUTH_MEMBER_ID_TOKEN (= '$auth.member_id') 사용 시 인증된 AppMember ID 로 서버가 치환합니다.

typescript

import { ConnectBase, AUTH_MEMBER_ID_TOKEN } from 'connectbase-client'

await cb.auth.signInMember({ login_id: 'alice', password: '...' })

// addDocument 시 metadata.user_id 자동 태깅
await cb.knowledge.addDocument('kb-id', { name: '내 메모', source_type: 'text', content: '...' })

// search 시 본인 문서로 자동 제한 + 추가 필터
await cb.knowledge.search('kb-id', {
    query: '내 메모',
    where: { 'metadata.tag': 'work' },
})

API 요약

메서드	설명
`cb.knowledge.addDocument(kbID, data)`	문서 추가 (text / url / file). `source_type='file'` 시 `file_content` (base64) + `mime_type`
`cb.knowledge.addDocumentFromFile(kbID, file, options?)`	파일 업로드 헬퍼 (3.17.0+). Blob/File/Buffer 입력 자동 변환
`cb.knowledge.listDocuments(kbID)`	문서 목록 조회
`cb.knowledge.deleteDocument(kbID, docID)`	문서 삭제 (청크 cascade)
`cb.knowledge.search(kbID, request)`	키워드 검색 (POST). `agentic: true` 로 AI 다중 쿼리
`cb.knowledge.searchGet(kbID, query, topK?)`	키워드 검색 (GET, 간단한 사용)

자주 발생하는 에러

에러	원인	해결
`Knowledge base not found`	잘못된 KB ID	콘솔에서 ID 확인
`Document still processing`	아직 ready 상태 아님	listDocuments 폴링으로 대기
`unsupported mime type for text extraction`	미지원 MIME (이미지/HWP/XLSX)	텍스트로 변환 후 source_type='text'
`file too large for extraction`	50MB 초과	분할 업로드
`extracted text is empty`	스캔 PDF / 빈 문서	OCR 결과 또는 원문 텍스트로 직접 입력
`AI provider not configured`	Agentic Search 시 AI 키 미설정	콘솔 > 설정 > AI 에서 프로바이더 등록

광고 (Ads)

에러 트래커 (Error Tracker)