첫 AI 분석

quant-ai의 Equity Reports 탭은 멀티 에이전트(Technical / Intel / Risk / Decision)가 협업해 작성하는 종목 분석 리포트를 제공합니다. 이 페이지에서는 LLM 키를 연결하고 첫 리포트를 생성합니다.

사전 준비

• 페이퍼 트레이딩 셋업 완료 (계정 + 페이퍼 키 1개 이상)
• LLM 접근 수단 1개 (택일):
  • OpenAI API 키 (sk-...)
  • 사내 LiteLLM 프록시 base_url + 키
  • Anthropic / Azure OpenAI (LiteLLM 경유)

---

Step 1: LLM 프록시 설정 (관리자 / 셀프 호스팅 시)

quant-ai는 LLM 호출을 LiteLLM 프록시로 일원화합니다. 운영 인스턴스는 보통 이미 설정되어 있으므로, 셀프 호스팅이거나 본인 키로 실험할 때만 해당됩니다.

서버 환경변수 (.env 또는 K8s Secret):

# OpenAI 직접 사용 시
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-xxxxxxxxxxxx

# 사내 LiteLLM 프록시 사용 시
OPENAI_BASE_URL=http://litellm-proxy.internal:4000/v1
OPENAI_API_KEY=sk-quant-ai-proxy-token
LLM_DEFAULT_MODEL=gpt-4o-mini

# Feature flag
FEATURE_LLM_ANALYSIS=true
FEATURE_EQUITY_ANALYSIS=true

자세한 설정: LiteLLM 프록시, 환경 변수.

Feature flag가 OFF인 경우

서버에 FEATURE_LLM_ANALYSIS / FEATURE_EQUITY_ANALYSIS 가 모두 OFF라면 POST /api/equity/analyze 가 503 을 반환합니다. UI는 “Feature is disabled” 배너로 가이드합니다.

---

Step 2: 분석 요청 (Equity → Reports)

2-1. 종목 선택

1. 좌측 사이드바 Equity 클릭
2. 상단 자산군 필터를 US 또는 KR 로 변경
3. Reports 탭 → 우측 New analysis 폼

종목 검색 결과를 선택하면 칩으로 추가됩니다. 예시:

• 미국: AAPL, MSFT, NVDA
• 한국: 005930 (삼성전자), 035720 (카카오)

2-2. 모드 선택

Mode	평균 소요	비용 (gpt-4o-mini 기준)	사용 시점
quick	~60초	~$0.01	인라인 호출 가능, 빠른 의사결정용
standard	~180초	~$0.05	기본값. 4 에이전트 풀 파이프라인
full	~240초	~$0.12	깊은 RAG + 다중 라운드 토론

인라인 모드는 mode=quick 만 허용됩니다. standard / full 은 항상 큐에 적재되어 워커가 처리합니다 (POST /api/equity/analyze 가 202 + queue_id 반환).

2-3. 제출

Analyze 버튼 클릭 시 다음 호출이 발생합니다:

POST /api/equity/analyze
Authorization: Bearer <access_token>

{
  "symbol": "AAPL",
  "mode": "standard",
  "inline": false,
  "priority": 5
}

응답:

{
  "report_id": "8b3f...uuid",
  "queue_id": 42,
  "status": "queued"
}

리포트가 queued → running → done 으로 전이되면 Reports 목록의 row 상태가 자동 갱신됩니다.

📸 분석 제출 직후의 리포트 카드 (추후 자동 캡처 예정)

레이트 리밋

사용자당 분당 5건 이 한도입니다 (토큰 버킷). 초과 시 429 RATE_LIMIT_EXCEEDED 가 반환됩니다.

---

Step 3: 리포트 결과 해석

리포트 카드를 클릭하면 우측 드로어에 상세가 표시됩니다.

📸 Report drawer 예시 (추후 자동 캡처 예정)

3-1. 핵심 헤더

필드	의미
decision	BUY / HOLD / SELL — Decision 에이전트의 최종 결론
score	-1.0 (강한 매도) ~ +1.0 (강한 매수) 정규화 점수
confidence	0.0 ~ 1.0, 에이전트 합의도
cost_usd	이번 분석에 누적 청구된 LLM 비용
risk_factors	Risk 에이전트가 식별한 위험 항목 리스트

3-2. 에이전트별 출력

리포트 본문은 4개 섹션으로 구성됩니다:

technical_output    →  지표/추세/볼륨/차트 패턴 (RSI, MACD, MA20/50)
intel_output        →  뉴스/공시/거시 지표 요약 + 출처
risk_output         →  변동성, 베타, 다운사이드 리스크, 이벤트 리스크
decision_output     →  종합 판단 + 시나리오 (bull / base / bear)

dashboard_md 필드는 위 4개를 합친 마크다운 형태로, UI 드로어에서 곧바로 렌더됩니다.

3-3. 에이전트 trace 살펴보기

GET /api/equity/reports/<report_id>/traces

각 에이전트의 step-by-step 추론(role: assistant, content, tokens_input/output, latency_ms)을 확인할 수 있어 왜 이런 결정이 나왔는지 추적할 수 있습니다.

---

Step 4: 리포트 → 거래 / 백테스트로 연결

리포트 드로어 하단의 액션 버튼:

• Add to watchlist — Watchlist 탭에 핀 고정
• Place paper order — Trade 탭으로 점프, report_uuid 가 자동으로 첨부됨
• Run backtest with this signal — Backtest 탭으로 종목 전달

report_uuid 가 첨부된 주문은 audit 로그 에서 “이 주문은 어떤 분석에서 나왔는지” 역추적이 가능합니다.

---

자주 보는 에러

응답	원인	해결
503 Feature disabled	FEATURE_LLM_ANALYSIS OFF	서버 환경변수 확인
422 Invalid symbol	자산군과 종목 코드 불일치 (예: AAPL 을 kr_equity로)	자산군 필터 또는 종목 재선택
429 RATE_LIMIT_EXCEEDED	분당 5건 초과	1분 대기 후 재시도
400 inline=True only for quick	큐를 우회하려 했음	mode=quick 로 변경 또는 inline=false

LLM 비용이 예상보다 빠르게 누적되면 LLM budget 트러블슈팅 가이드를 참고하세요.

---

다음 단계: 첫 백테스트에서 분석 결과를 과거 OHLCV에 적용해 정량적으로 검증합니다.