TruthAnchor - 사용자 매뉴얼

시작하기

사전 요구사항

Docker Desktop (v4.0+)
Python 3.12+
uv (Python 패키지 매니저)
Anthropic API Key 또는 OpenAI API Key

설치 및 초기 설정

1

의존성 설치

make setup

2

인프라 기동 (Qdrant, Neo4j, PostgreSQL, Redis, Kafka)

make infra-up

3

환경 변수 설정

cp .env.example .env
# .env 파일을 편집하여 API 키를 입력하세요
# ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...

4

테스트 데이터 인덱싱

make seed-data

5

전 서비스 실행

make run-all

API 키 발급

회원가입 후 로그인합니다.
대시보드에서 API Keys 탭으로 이동합니다.
새 키 발급 버튼을 클릭하고 키 이름을 입력합니다.
발급된 키를 안전한 곳에 복사하여 저장합니다. (키는 한 번만 표시됩니다.)

API Key는 발급 시 한 번만 표시됩니다. 반드시 안전한 곳에 저장하세요.

Chat API 사용법

기본 요청

TruthAnchor Chat API는 POST /api/v1/chat 엔드포인트를 통해 접근합니다. 모든 요청에는 X-API-Key 헤더가 필요합니다.

요청 예제

curl -X POST https://your-domain.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ta_xxxxxxxxxxxx" \
  -d '{
    "message": "예금 금리가 가장 높은 상품은?",
    "domain": "banking",
    "conversation_id": "conv-001",
    "stream": false
  }'

응답 예제

{
  "answer": "현재 가장 높은 예금 금리를 제공하는 상품은...",
  "confidence": 0.94,
  "citations": [
    {
      "source": "deposit_rates_2025.pdf",
      "page": 3,
      "text": "정기예금 최고 금리 3.8%..."
    }
  ],
  "uncertainty_score": 0.06,
  "guardrail_passed": true,
  "model": "claude-sonnet-4-20250514",
  "processing_time_ms": 142,
  "conversation_id": "conv-001"
}

스트리밍 요청

"stream": true를 설정하면 Server-Sent Events (SSE)로 실시간 응답을 받을 수 있습니다.

curl -X POST https://your-domain.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ta_xxxxxxxxxxxx" \
  -d '{"message": "대출 한도 조회", "stream": true}'

피드백 전송

curl -X POST https://your-domain.com/api/v1/chat/feedback \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ta_xxxxxxxxxxxx" \
  -d '{
    "conversation_id": "conv-001",
    "message_id": "msg-abc123",
    "rating": "good",
    "comment": "정확한 답변이었습니다."
  }'

모든 API 요청에는 Rate Limit이 적용됩니다. Free 플랜은 분당 10회, Starter 플랜은 분당 60회까지 호출 가능합니다.

대시보드 사용법

메뉴	설명
개요	이번 달 API 사용량, 현재 플랜, 활성 API Key 수, RPM 한도를 한눈에 확인합니다.
API Keys	API Key를 발급, 조회, 삭제할 수 있습니다. 키는 발급 시 한 번만 표시됩니다.
사용량	최근 6개월간 월별 API 요청 수를 확인합니다.
결제	현재 구독 상태, 결제 내역, 구독 해지 기능을 제공합니다.
RAG 문서	인덱싱된 RAG 문서를 조회, 검색, 삭제할 수 있습니다. 카테고리별 필터링이 가능합니다.
QA 채팅	미리 정의된 테스트 케이스로 플랫폼의 응답 품질을 검증합니다. PII 마스킹, 인젝션 방어 등을 테스트합니다.
관리자	시스템 상태, LLM 비용, 가드레일 규칙, HITL 케이스, DLQ 등 운영 관련 기능을 관리합니다.

플러그인 설정 방법

TruthAnchor는 플러그인 아키텍처를 통해 LLM, 검색기, 가드레일, 불확실성 계산기를 교체할 수 있습니다.

플러그인 인터페이스

플러그인 유형	인터페이스	설명
LLM Provider	`LLMProvider`	새로운 LLM 모델 추가 (Claude, GPT, Llama 등)
Retriever	`Retriever`	검색 엔진 추가 (Qdrant, Elasticsearch 등)
Guardrail	`Guardrail`	출력 검증 규칙 추가
Uncertainty Scorer	`UncertaintyScorer`	불확실성 점수 계산 알고리즘 추가

플러그인 등록

구현한 플러그인을 config/plugins.yaml에 등록하면 자동으로 로드됩니다.

# config/plugins.yaml
plugins:
  llm_providers:
    - name: "claude-sonnet"
      module: "services.evidence_generation.providers.claude"
      class: "ClaudeProvider"
      config:
        model: "claude-sonnet-4-20250514"
        max_tokens: 4096

  retrievers:
    - name: "qdrant-hybrid"
      module: "services.evidence_generation.retrievers.qdrant"
      class: "QdrantHybridRetriever"
      config:
        collection: "finance_docs"
        top_k: 5

  guardrails:
    - name: "financial-compliance"
      module: "services.output_verification.guards.compliance"
      class: "FinancialComplianceGuard"
      enabled: true

자주 묻는 질문 (FAQ)

Q1. TruthAnchor는 어떤 LLM을 지원하나요?

현재 Anthropic Claude (claude-sonnet-4-20250514)를 기본 모델로 사용하며, OpenAI GPT-4o를 폴백 모델로 지원합니다. 플러그인 인터페이스를 통해 다른 LLM도 추가할 수 있습니다.

Q2. 무료 플랜의 제한 사항은 무엇인가요?

Free 플랜은 월 500회 API 호출, 분당 10회 요청(RPM), API Key 2개까지 발급 가능합니다. 더 많은 호출이 필요하면 Starter 또는 Enterprise 플랜으로 업그레이드하세요.

Q3. PII(개인정보) 마스킹은 어떻게 동작하나요?

Layer 1(입력 거버넌스)에서 주민등록번호, 전화번호, 계좌번호 등의 개인정보를 자동으로 감지하고 마스킹합니다. 마스킹된 데이터는 LLM에 전달되지 않으며, 감사 로그에도 마스킹된 형태로만 저장됩니다.

Q4. 할루시네이션 탐지율 97%는 어떻게 달성하나요?

4계층 파이프라인의 조합으로 달성합니다: RAG 기반 근거 검색(Layer 2), 가드레일 규칙 검증(Layer 3), 불확실성 점수 계산(Layer 3), 전문가 에스컬레이션(Layer 4)이 함께 작동합니다.

Q5. 스트리밍 응답은 어떻게 사용하나요?

요청 body에 "stream": true를 추가하면 Server-Sent Events(SSE) 형식으로 실시간 응답을 받을 수 있습니다. 각 이벤트는 data: 접두사와 함께 JSON 형태로 전달됩니다.

Q6. 에스컬레이션은 언제 발생하나요?

불확실성 점수가 임계값(기본 0.7)을 초과하거나, 고액 거래 관련 질문, 가드레일이 차단한 응답 등의 경우 자동으로 전문가 검토(HITL)로 에스컬레이션됩니다.

Q7. 지원하는 도메인은 무엇인가요?

금융/은행, 보험, 증권, 카드, 교육, 헬스케어, 법률, IT, 정부행정, 국방 등 10개 이상의 도메인을 지원합니다. 각 도메인별로 특화된 가드레일과 프롬프트 템플릿이 적용됩니다.

Q8. API Key가 유출되었을 때 어떻게 하나요?

대시보드의 API Keys 탭에서 해당 키를 즉시 삭제(비활성화)하세요. 비활성화된 키로는 더 이상 API 호출이 불가합니다. 이후 새 키를 발급하여 사용하세요.

Q9. 자체 문서를 RAG에 추가할 수 있나요?

네, 대시보드의 RAG 문서 탭에서 PDF 파일을 업로드하면 자동으로 청크 분할 및 벡터 인덱싱이 수행됩니다. CLI로는 make seed-data 명령을 사용할 수도 있습니다.

Q10. 구독을 해지하면 데이터는 어떻게 되나요?

구독 해지 시 현재 결제 기간이 끝나는 시점에 Free 플랜으로 전환됩니다. 데이터(RAG 문서, 대화 기록, 감사 로그)는 90일간 보관된 후 삭제됩니다.

문제 해결 가이드

인프라가 기동되지 않는 경우

Docker Desktop이 실행 중인지 확인하세요. 포트 충돌이 발생할 수 있으므로 기존에 사용 중인 포트(6333, 7687, 5432, 6379, 9092)를 확인하세요.

# 포트 사용 현황 확인
lsof -i :6333  # Qdrant
lsof -i :7687  # Neo4j
lsof -i :5432  # PostgreSQL

# 인프라 재시작
make infra-down && make infra-up

API 호출 시 401 Unauthorized

API Key가 올바른지 확인하세요. 키가 비활성화되었거나 만료되었을 수 있습니다. 대시보드에서 키 상태를 확인하세요.

# 올바른 헤더 형식
X-API-Key: ta_xxxxxxxxxxxx

# 잘못된 형식 (Bearer 아님)
Authorization: Bearer ta_xxxxxxxxxxxx  # X

API 호출 시 429 Rate Limit Exceeded

분당 요청 한도를 초과했습니다. 잠시 후 재시도하거나 상위 플랜으로 업그레이드하세요.

RAG 검색 결과가 없는 경우

문서가 인덱싱되었는지 확인하세요. Qdrant가 정상 동작 중인지 확인하고, 문서를 다시 인덱싱해보세요.

# Qdrant 상태 확인
curl http://localhost:6333/collections

# 문서 재인덱싱
make seed-data

높은 불확실성 점수가 지속되는 경우

RAG 지식베이스에 관련 문서가 부족할 수 있습니다. 해당 도메인의 문서를 추가로 인덱싱하세요. 또는 질문이 지원 도메인 범위를 벗어났을 수 있습니다.

LLM 응답이 느린 경우

LLM API의 응답 지연이 원인일 수 있습니다. 캐시를 활성화하면 반복 질문에 대해 빠른 응답이 가능합니다. Redis 연결 상태도 확인하세요.

# Redis 연결 확인
redis-cli ping

# 시스템 상태 확인
curl http://localhost:8000/api/v1/health