기술 문서

TruthAnchor는 모든 요청을 4개의 독립된 계층을 순차적으로 통과시켜 할루시네이션을 방지합니다. 각 계층은 독립적으로 운영되며, 장애 시 Circuit Breaker를 통해 Graceful Degradation이 적용됩니다.

Base URL: https://your-domain.com

모든 API 호출에는 X-API-Key 헤더가 필요합니다. (Health, Metrics 제외)

{
  "answer": "응답 텍스트...",
  "confidence": 0.94,
  "uncertainty_score": 0.06,
  "citations": [
    {
      "source": "document.pdf",
      "page": 3,
      "text": "인용된 원문...",
      "relevance_score": 0.92
    }
  ],
  "guardrail_passed": true,
  "guardrail_details": {
    "triggered_rules": [],
    "blocked": false
  },
  "model": "claude-sonnet-4-20250514",
  "processing_time_ms": 142,
  "conversation_id": "conv-001",
  "message_id": "msg-abc123",
  "layers": {
    "l1_input_governance": {"status": "pass", "duration_ms": 12},
    "l2_evidence_generation": {"status": "pass", "duration_ms": 98},
    "l3_output_verification": {"status": "pass", "duration_ms": 28},
    "l4_escalation": {"status": "none", "duration_ms": 4}
  }
}

{"status": "ok", "feedback_id": "fb-xyz789"}

{
  "status": "healthy",
  "version": "1.0.0",
  "layers": {
    "input_governance": {"status": "healthy", "latency_ms": 2},
    "evidence_generation": {"status": "healthy", "latency_ms": 5},
    "output_verification": {"status": "healthy", "latency_ms": 3},
    "escalation": {"status": "healthy", "latency_ms": 1}
  },
  "components": {
    "qdrant": "connected",
    "neo4j": "connected",
    "postgresql": "connected",
    "redis": "connected",
    "kafka": "connected"
  },
  "timestamp": "2026-03-11T09:00:00Z"
}

# HELP truthanchor_requests_total Total number of requests
# TYPE truthanchor_requests_total counter
truthanchor_requests_total{method="POST",endpoint="/api/v1/chat"} 12847

# HELP truthanchor_latency_seconds Request latency in seconds
# TYPE truthanchor_latency_seconds histogram
truthanchor_latency_seconds_bucket{le="0.1"} 9821
truthanchor_latency_seconds_bucket{le="0.2"} 12102
truthanchor_latency_seconds_bucket{le="0.5"} 12780

# HELP truthanchor_hallucination_detected_total Hallucinations detected
# TYPE truthanchor_hallucination_detected_total counter
truthanchor_hallucination_detected_total 47

# HELP truthanchor_guardrail_triggered_total Guardrail rule triggers
# TYPE truthanchor_guardrail_triggered_total counter
truthanchor_guardrail_triggered_total{rule="CG-001"} 23

불확실성 점수는 LLM 응답의 신뢰도를 0.0 ~ 1.0 범위로 정량화합니다. 점수가 낮을수록 응답이 더 신뢰할 수 있음을 의미합니다.

계산 공식

임계값 기준

Citation Coverage는 LLM 응답의 각 문장이 RAG 검색 결과에 의해 뒷받침되는지 측정합니다.

처리 과정

1. LLM 응답을 문장 단위로 분할합니다.
2. 각 문장을 RAG에서 검색된 문서 청크와 의미적 유사도를 비교합니다.
3. 유사도가 임계값(0.75) 이상인 청크를 해당 문장의 citation으로 연결합니다.
4. Citation이 연결된 문장 수 / 전체 문장 수 = Citation Coverage 비율

가드레일 규칙은 LLM 응답이 금융 규정 및 안전성 기준을 충족하는지 검증합니다. 규칙은 config/guardrails/에 YAML로 정의됩니다.

TruthAnchor는 외부 서비스 장애 시 Circuit Breaker 패턴을 적용하여 서비스 안정성을 보장합니다.

Circuit Breaker 상태

Graceful Degradation 단계

1. Level 0 (Normal) - 모든 기능 정상 동작
2. Level 1 (Primary LLM Fallback) - 주 LLM 장애 시 보조 LLM으로 전환
3. Level 2 (Cache-Only) - LLM 전면 장애 시 캐시된 응답만 반환
4. Level 3 (Static Response) - 모든 외부 서비스 장애 시 정적 안내 메시지 반환

설치

pip install truthanchor-sdk

기본 사용법

from truthanchor import TruthAnchorClient

client = TruthAnchorClient(
    api_key="ta_xxxxxxxxxxxx",
    base_url="https://your-domain.com"
)

# 동기 요청
response = client.chat(
    message="예금 금리 비교해 주세요",
    domain="banking"
)
print(response.answer)
print(f"신뢰도: {response.confidence}")
print(f"불확실성: {response.uncertainty_score}")

# 스트리밍 요청
for chunk in client.chat_stream(message="대출 한도 조회"):
    print(chunk.text, end="", flush=True)

# 피드백 전송
client.send_feedback(
    conversation_id=response.conversation_id,
    message_id=response.message_id,
    rating="good"
)

비동기 사용법

import asyncio
from truthanchor import AsyncTruthAnchorClient

async def main():
    client = AsyncTruthAnchorClient(api_key="ta_xxxxxxxxxxxx")
    response = await client.chat(message="보험 상품 추천")
    print(response.answer)

asyncio.run(main())

에러 처리

from truthanchor.exceptions import (
    RateLimitError,
    AuthenticationError,
    ServiceDegradedError
)

try:
    response = client.chat(message="질문")
except RateLimitError as e:
    print(f"Rate limit exceeded. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except ServiceDegradedError as e:
    print(f"Service degraded: {e.degradation_level}")

TruthAnchor는 Kafka를 통해 내부 이벤트를 발행하며, 외부 시스템에 Webhook으로 알림을 전송할 수 있습니다.

이벤트 유형

Webhook Payload 예제

{
  "event": "escalation.created",
  "timestamp": "2026-03-11T09:15:30Z",
  "data": {
    "case_id": "esc-001",
    "reason": "uncertainty_threshold_exceeded",
    "uncertainty_score": 0.82,
    "conversation_id": "conv-123",
    "priority": "high"
  }
}

Rate Limiting

보안 헤더

Rate Limit 관련 응답 헤더:

X-RateLimit-Limit: 60          # 분당 허용 요청 수
X-RateLimit-Remaining: 45      # 남은 요청 수
X-RateLimit-Reset: 1710147600  # 리셋 타임스탬프 (Unix)

보안 조치

• 모든 통신은 TLS 1.3으로 암호화됩니다.
• API Key는 SHA-256으로 해시되어 저장됩니다.
• 입력 데이터의 PII는 처리 전 마스킹됩니다.
• 감사 로그는 PostgreSQL에 30일간 보관됩니다.
• 프롬프트 인젝션 공격은 Layer 1에서 실시간 탐지/차단됩니다.
• 반복된 인증 실패 시 IP 기반 임시 차단이 적용됩니다.