개요
API Keys
API Key 사용 가이드
Quick Start
모든 API 요청의 HTTP 헤더에 X-API-Key 를 포함하세요.
X-API-Key: ta_xxxxxxxxxxxx
curl -X POST http://localhost:8000/api/v1/chat \
-H "Content-Type: application/json" \
-H "X-API-Key: ta_xxxxxxxxxxxx" \
-d '{"message": "예금 금리 알려줘", "session_id": "s1"}'
from sdk.python import TruthAnchorClient
client = TruthAnchorClient(
base_url="http://localhost:8000",
api_key="ta_xxxxxxxxxxxx",
)
# 동기 호출
response = client.chat("한국은행 기준금리 알려줘")
print(response.content)
print(f"불확실성: {response.uncertainty_score:.3f}")
print(f"인용: {len(response.citations)}건")
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "ta_xxxxxxxxxxxx",
},
body: JSON.stringify({
message: "예금 금리 알려줘",
session_id: "session-001"
}),
});
const data = await res.json();
console.log(data.content);
| Method | Endpoint | 설명 |
|---|---|---|
| POST | /api/v1/chat | 채팅 요청 (동기/스트리밍) |
| POST | /api/v1/chat/feedback | 응답 피드백 전송 |
| GET | /api/v1/health | 시스템 상태 확인 |
| GET | /api/v1/metrics | Prometheus 메트릭 |
"session_id": "s1",
"content": "현재 한국은행 기준금리는...",
"citations": [
{ "source": "한국은행", "excerpt": "...", "relevance_score": 0.95 }
],
"metadata": {
"uncertainty_score": 0.12, // 0.0(확신) ~ 1.0(불확실)
"intent": "interest_rate",
"guardrail_results": { "passed": true, "violations": [] },
"escalated": false
},
"disclaimer": "※ 참고용 정보입니다."
}
- API Key는 발급 시 한 번만 표시됩니다. 안전한 곳에 보관하세요.
- Key가 노출되었다면 즉시 비활성화하고 새 키를 발급하세요.
- Key를 클라이언트(브라우저) 코드에 직접 포함하지 마세요.
- 환경변수(
TRUTHANCHOR_API_KEY)로 관리하는 것을 권장합니다. - Rate Limit: Free 10 RPM / Starter 60 RPM / Enterprise 500 RPM
사용량
| 월 | 요청 수 |
|---|---|
| 로딩 중... | |
결제 내역
| 날짜 | 금액 | 상태 |
|---|---|---|
| 로딩 중... | ||
RAG 문서 관리
파일 내용(SHA-256)을 기준으로 중복을 판단합니다. 동일 내용의 파일은 파일명이 달라도 자동으로 건너뜁니다.
같은 파일명이라도 내용이 변경된 경우(개정판 등)에는 정상적으로 재인덱싱됩니다. 이미지 기반 PDF는 OCR로 자동 처리됩니다.
| 카테고리 | 파일명 | 청크 수 | 파일 크기 | 시행일 | 파일 | 작업 | |
|---|---|---|---|---|---|---|---|
| 로딩 중... | |||||||
개념 탐색 /
도메인 필터
그래프 통계
개념을 검색하여 탐색을 시작하세요.
단축키:
Esc 선택 해제 F 전체 보기
Space 물리 일시정지 P 성능 통계
/ 검색 포커스
일반 RAG vs TruthAnchor 비교
규제 타임라인
할루시네이션 검증
실시간 검증
AI 응답과 근거 자료를 입력하면 할루시네이션 여부를 실시간으로 검증합니다.
데모 시나리오
아래 버튼을 클릭하면 대표적인 할루시네이션 유형을 체험할 수 있습니다.
배치 검증
여러 건의 응답을 한 번에 검증합니다. JSON 형식으로 입력하세요.
뉴스 & 투자보고서
뉴스 수집 / 팩트체크
연합뉴스, 뉴시스
서울경제, 머니투데이
비즈니스 전문 블로그
출처 불명
최근 뉴스 피드
투자보고서 생성
플레이그라운드
Documentation
TruthAnchor는 금융 서비스에서 LLM(대형 언어 모델)을 신뢰할 수 있는 챗봇/에이전트로 활용하기 위한 다층 할루시네이션 방어 플랫폼입니다. 금융 규제·컴플라이언스 요건을 충족하면서 정확하고 근거 기반의 응답을 제공합니다.
4계층 아키텍처
| 계층 | 이름 | 주요 기능 |
|---|---|---|
| Layer 1 | 입력 거버넌스 | Intent 분류, PII 마스킹, 프롬프트 인젝션 방어 |
| Layer 2 | 근거 기반 생성 | Hybrid RAG, LLM 생성, Citation Linker |
| Layer 3 | 출력 검증 | 컴플라이언스 가드레일, 수치 검증, 불확실성 점수화 |
| Layer 4 | 에스컬레이션 | 감사 로그, 에스컬레이션 라우터 |
주요 성과 지표 (Phase 3 목표)
| 지표 | 목표 | 설명 |
|---|---|---|
| 할루시네이션 탐지율 | ≥ 97% | 4-Signal 복합 불확실성 점수 기반 탐지 |
| 응답 지연 p95 | ≤ 200ms | 전체 파이프라인 처리 시간 (LLM 호출 제외) |
| 금융 RAG 정확도 | ≥ 98% | 근거 문서 기반 정확한 응답 비율 |
1. API Key 발급
Dashboard의 API Keys 탭에서 "새 키 발급" 버튼을 클릭합니다. 발급된 키는 한 번만 표시되므로 반드시 안전한 곳에 저장하세요.
2. 첫 번째 API 호출 (curl)
3. 첫 번째 API 호출 (Python)
4. 응답 구조
uncertainty_score: 0.0 (매우 확신) ~ 1.0 (불확실). 0.6 이상이면 자동 에스컬레이션됩니다.
citations: 근거 문서의 출처, 페이지, 관련 스니펫.
guardrail_results: 가드레일 검증 통과 여부와 위반 내역.
TruthAnchor는 4개의 신호를 결합한 복합 불확실성 점수를 산출합니다.
| Signal | 설명 | 가중치 |
|---|---|---|
| Token Entropy | LLM 출력 토큰의 엔트로피. 높을수록 모델이 불확실 | 25% |
| Semantic Consistency | 동일 질문에 대한 복수 응답 간 의미적 일관성 | 30% |
| Claim Verification | 응답 내 주장(claim)이 근거 문서와 일치하는지 검증 | 30% |
| ECE (Expected Calibration Error) | 모델 자체 신뢰도 보정 오차 | 15% |
점수 해석 가이드
| 범위 | 상태 | 조치 |
|---|---|---|
| 0.0 ~ 0.3 | 높은 신뢰 | 응답을 그대로 사용 가능 |
| 0.3 ~ 0.6 | 주의 필요 | 사용자에게 불확실성 고지 권장 |
| 0.6 ~ 1.0 | 에스컬레이션 | 자동으로 사람 상담원에게 전달 |
채팅 요청을 전송합니다. 4계층 파이프라인을 거쳐 근거 기반 응답을 반환합니다.
Headers
| Name | Required | Description |
|---|---|---|
| X-API-Key | Yes | API 인증 키 (ta_xxxx...) |
| Content-Type | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | 사용자 질문 메시지 |
| session_id | string | No | 세션 ID (대화 유지용) |
| options.stream | boolean | No | 스트리밍 응답 여부 (default: false) |
| options.include_citations | boolean | No | 인용 포함 여부 (default: true) |
| options.max_tokens | integer | No | 최대 응답 토큰 수 (default: 1024) |
Request Example
Response (200 OK)
Error Responses
| Status | Code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | API 키 누락 또는 유효하지 않음 |
| 429 | RATE_LIMITED | RPM 한도 초과 |
| 400 | INVALID_REQUEST | 요청 형식 오류 |
| 500 | INTERNAL_ERROR | 서버 내부 오류 |
응답에 대한 사용자 피드백을 전송합니다. 모델 개선 및 감사 로그에 활용됩니다.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| request_id | string | Yes | 피드백 대상 요청 ID |
| rating | string | Yes | "positive" | "negative" |
| comment | string | No | 추가 코멘트 |
Example
시스템 상태를 계층별로 확인합니다. 인증 불필요.
Response (200 OK)
Prometheus 형식의 메트릭을 반환합니다. 모니터링 시스템(Grafana 등)과 연동하여 사용합니다.
주요 메트릭
| Metric | Type | Description |
|---|---|---|
| ta_requests_total | Counter | 총 API 요청 수 |
| ta_latency_seconds | Histogram | 요청 처리 시간 (초) |
| ta_hallucination_detected_total | Counter | 할루시네이션 탐지 횟수 |
| ta_escalation_total | Counter | 에스컬레이션 발생 횟수 |
| ta_guardrail_violations_total | Counter | 가드레일 위반 횟수 |
| ta_uncertainty_score | Histogram | 불확실성 점수 분포 |
TruthAnchor는 금융 컴플라이언스를 위해 다음의 가드레일 규칙을 적용합니다. 모든 LLM 응답은 이 규칙들을 통과해야 사용자에게 전달됩니다.
| 규칙 ID | 이름 | 설명 | 심각도 |
|---|---|---|---|
| CG-001 | 투자 권유 금지 | 특정 종목·상품에 대한 직접적 투자 권유 또는 매수/매도 추천 차단 | Critical |
| CG-002 | 수익률 보장 금지 | 확정 수익률, 원금 보장 등 허위·과장 표현 차단 | Critical |
| CG-003 | 수치 정확성 검증 | 금리, 환율, 수수료 등 수치 데이터가 근거 문서와 허용 오차(0.1%) 내 일치 검증 | Critical |
| CG-004 | 출처 명시 의무 | 응답에 반드시 근거 문서 출처(법령명, 조항, 페이지)를 포함해야 함 | High |
| CG-005 | 면책 조항 포함 | 투자·세금 관련 응답에 "본 정보는 참고용이며 투자 판단의 근거가 아닙니다" 면책 문구 포함 | High |
| CG-006 | 개인정보 노출 방지 | 응답에 마스킹되지 않은 PII(주민번호, 계좌번호 등)가 포함되지 않도록 검증 | Critical |
| CG-007 | 시점 명시 | 규정·금리 등 시간에 따라 변하는 정보에 기준 시점(시행일, 적용일)을 명시 | High |
| CG-008 | 불확실성 고지 | 불확실성 점수 0.3 이상 시 응답에 "정보의 정확성이 완전히 확인되지 않았습니다" 고지 | Medium |
가드레일 위반이 감지되면 다음과 같이 처리됩니다:
| 단계 | 동작 | 설명 |
|---|---|---|
| 1 | 위반 감지 | Layer 3에서 규칙 위반 식별 |
| 2 | 심각도 판정 | Critical: 응답 차단 / High: 수정 후 전달 / Medium: 경고 첨부 |
| 3 | 감사 로그 기록 | 위반 내용, 원본 응답, 판정 결과를 불변 로그에 기록 |
| 4 | 에스컬레이션 (Critical) | Critical 위반 시 사람 상담원에게 자동 전달 |
| 5 | 대체 응답 생성 | 안전한 대체 응답 또는 "확인 후 답변드리겠습니다" 메시지 반환 |
설치
또는 최신 개발 버전:
재시도 설정
TruthAnchor에 수집되는 모든 뉴스는 자동 팩트체크를 거쳐 신뢰도 등급이 부여됩니다. 등급은 출처 신뢰도 + 수치 검증 + 이슈 분석을 종합하여 결정됩니다.
| 등급 | 신뢰도 | 기준 | 해당 출처 |
|---|---|---|---|
| A | ≥ 0.9 | 공식 기관, 국가 통신사 | 한국은행, 금융위원회, 금융감독원, 연합뉴스, 뉴시스 |
| B | ≥ 0.7 | 경제 전문지 | 한국경제, 매일경제, 서울경제, 머니투데이, 이데일리 |
| C | ≥ 0.5 | 일반 언론, 전문 블로그 | 일반 매체, 비즈니스 전문 블로그 |
| D | < 0.5 | 미확인 출처 | 개인 블로그, SNS, 출처 불명 |
출처(언론사)별로 사전 정의된 신뢰도 점수가 적용됩니다. 금융 공식 기관이 가장 높고, 미등록 출처가 가장 낮습니다.
| 점수 | 출처 | 분류 |
|---|---|---|
| 1.00 | 한국은행, 금융위원회, 금융감독원 | 공식 기관 |
| 0.95 | 연합뉴스 | 국가 통신사 |
| 0.90 | 뉴시스 | 통신사 |
| 0.85 | 한국경제, 매일경제, 서울경제 | 경제 전문지 |
| 0.80 | 머니투데이, 이데일리, 파이낸셜뉴스 | 경제 매체 |
| 0.75 | 조선비즈, 한경비즈니스 | 비즈니스 매체 |
| 0.50 | 기타 / 미등록 출처 | 기본값 |
뉴스가 수집될 때 3단계 검증을 거쳐 최종 등급이 결정됩니다.
투자보고서에서는 각 문장에 출처 태그가 표기되어 정보의 근거를 명확히 구분합니다.
| 태그 | 등급 | 의미 | 표기 예시 |
|---|---|---|---|
| [규제] | A | 법령/공시 기반 (확정 사실) | [규제] 예금자보호법에 따라... |
| [뉴스] | B | 복수 뉴스 교차확인 | [뉴스] 한경/매경에 따르면... |
| [시세] | A | 실시간 시세 데이터 | [시세] 기준금리 2.75% |
| [뉴스*] | C | 단일 뉴스 (추가 확인 권장) | [뉴스*] ○○경제에 따르면... |
| [추론] | D | AI 추론 (근거 없음, 주의 필요) | [추론] 향후 금리 인하 가능성... |
⚠ [추론] 태그가 붙은 문장은 사실이 아닐 수 있습니다. 투자 결정에 활용하기 전 반드시 추가 확인이 필요합니다.
| 뉴스 등급 | 보고서에서 | 의미 |
|---|---|---|
| A등급 뉴스 2개+ 교차확인 | B (복수뉴스) 신뢰도 | 높은 확신으로 인용 |
| A/B등급 단일 뉴스 | C (단일뉴스) 신뢰도 | 참고 수준으로 인용 |
| C등급 뉴스 | 인용 시 경고 표시 | 추가 확인 권장 |
| D등급 뉴스 | 보고서에서 제외 가능 | 신뢰할 수 없는 출처 |
뉴스를 기반으로 생성된 보고서에 추가로 적용되는 5개 전용 가드레일입니다.
| 규칙 | 명칭 | 설명 |
|---|---|---|
| CG-030 | 출처 누락 탐지 | 수치 포함 문장에 출처 태그([뉴스], [규제])가 없으면 탐지 |
| CG-031 | 내용 과장 탐지 | 뉴스 원문 "소폭 조정" → 보고서 "폭락"으로 과장 시 탐지 |
| CG-032 | 단일 출처 의존 | 전체 인용의 70%+ 가 한 출처에서 올 경우 경고 |
| CG-033 | 오래된 뉴스 현재화 | 7일+ 지난 뉴스를 "오늘", "현재"로 서술 시 차단 |
| CG-034 | 상충 뉴스 누락 | 긍정/부정 상반된 뉴스 중 한쪽만 인용 시 탐지 |
| 방법 | 설명 | 사용법 |
|---|---|---|
| RSS 자동 수집 | 연합뉴스/한경/매경 RSS에서 키워드 관련 뉴스 자동 수집 | 뉴스 & 보고서 > 키워드 입력 > "뉴스 수집" 클릭 |
| 수동 입력 | 뉴스 제목/본문/출처 직접 입력 | 뉴스 & 보고서 > 왼쪽 폼 > "수집 & 인덱싱" 클릭 |
| API 호출 | 외부 시스템에서 API로 전송 | POST /api/v2/news/ingest |
| 피드 조회 | 저장소에서 키워드 기반 검색 | GET /api/v2/news/feed?keyword=금리 |
금융권 망분리는 전자금융감독규정 제15조, 제32조에 의해 모든 금융기관에 의무화된 보안 원칙입니다. 금융전산 시스템을 인터넷과 물리적/논리적으로 격리하여 고객 정보를 보호합니다.
| 원칙 | 요구사항 | TruthAnchor 대응 |
|---|---|---|
| 물리적 분리 | 인터넷/업무망 분리 | DMZ Proxy 경유 |
| 접근 통제 | 허가 트래픽만 통과 | 호스트 화이트리스트 (2개만 허용) |
| 데이터 보호 | 고객 정보 유출 금지 | PII 양방향 검사 + ARIA/SEED 암호화 |
| 감사 추적 | 외부 통신 전 건 기록 | HMAC-SHA256 감사 로그 5년 보관 |
| 장애 격리 | 외부 장애 내부 전파 차단 | 서킷 브레이커 + LLM 캐시 |
A. DMZ 경유 (대부분 금융사)
외부 LLM API를 DMZ Proxy를 통해서만 호출합니다. 고객 데이터는 업무망에서만 처리되며, PII는 외부로 유출되지 않습니다.
B. 완전 폐쇄망 (보안 최상위)
인터넷 연결 없이 자체 호스팅 LLM(vLLM, TGI, Ollama)을 사용합니다. 모든 데이터가 내부망에서만 처리됩니다.
C. 금융 클라우드 (CSAP 인증)
NHN Cloud 금융존, NCP 금융클라우드 등 금융위 허가 CSAP 인증 클라우드에서 운영합니다.
| 기능 | 설명 |
|---|---|
| 호스트 화이트리스트 | api.anthropic.com, api.openai.com만 허용 |
| PII 유출 검사 | 주민번호, 카드번호, 계좌번호, 전화번호, 이메일 차단 |
| 감사 로깅 | 전 건 HMAC-SHA256 서명, 5년 보관 |
| 서킷 브레이커 | 외부 API 장애 시 자동 격리 |
| 동시 요청 제한 | asyncio.Semaphore (기본 50건) |
| 본문 크기 제한 | 10MB |
| 항목 | 상태 |
|---|---|
| DMZ Proxy 화이트리스트 | 구현됨 |
| TLS 1.3 / mTLS | 구현됨 |
| PII 유출 검사 | 구현됨 |
| 감사 로그 5년 보관 | 구현됨 |
| ARIA/SEED 암호화 | 구현됨 |
| OAuth 2.0 인증 | 구현됨 |
| Multi-Region DR | 구현됨 |
| ISMS-P 인증 | 준비 중 |
| 지표 | 100건 벤치마크 | 600건 벤치마크 |
|---|---|---|
| 할루시네이션 탐지율 | 100.0% (46/46) | 96.8% (+Judge) |
| False Positive | 0.0% (0/54) | 4.1% (패턴+NLI) |
| 가드레일 규칙 | 38개 (CG-001~028 + NLI + Judge) + 뉴스 5개 (CG-030~034) | |
| 벤치마크 | 600건 (36개 카테고리) | |
| 3단계 방어 | 패턴 (<1ms) → NLI (~50ms) → Judge (~2s) | |
보고서 이력
RAG 컨텍스트 없이 생성
검증 레이어 적용 전
가드레일 · Citation · 수치검증
분석 결과가 표시됩니다