포트폴리오 — 동일 가중치 vs 최대 샤프(Sharpe) 최적화
티커 형식은 reference.md를 참조하세요.
사전 조건
GET http://localhost:8000/health
{"status": "ok"}를 반환해야 합니다. 그렇지 않으면 사용자에게 python backend/run.py를 실행하라고 안내하세요.
1단계 — 티커 추출
- 메시지에서 모든 티커 심볼을 추출합니다. 대문자로 변환하고 공백을 제거합니다.
- 최소 2개, 최대 10개입니다. 중복은 API에서 거부하므로 — 자동으로 중복을 제거하고 이를 알립니다.
- 티커가 2개 미만이면 진행하기 전에 더 입력해 달라고 요청하세요.
2단계 — 포트폴리오 작업 제출
POST http://localhost:8000/api/v1/portfolio
Content-Type: application/json
{"tickers": ["T1", "T2", "..."], "query": "최대 위험 조정 수익률을 위한 배분 최적화."}
응답: {"job_id": "<uuid>", "status": "pending", "message": "..."}
사용자에게 알립니다:
{n}개 티커에 대한 포트폴리오 작업이 제출되었습니다. 1년 가격 이력을 가져와 최적화 중… 일반적으로 15~30초 소요됩니다.
3단계 — 상태 폴링
GET http://localhost:8000/api/v1/status/{job_id}
completed 또는 failed 상태가 될 때까지 5초마다 폴링합니다.
4단계 — 결과 가져오기
GET http://localhost:8000/api/v1/result/{job_id}
오류 케이스
결과에 최상위 error 키가 포함된 경우 (예: "가격 이력이 중복되는 최소 두 개의 티커가 필요합니다"), 문제를 평이한 언어로 설명하고 중단합니다:
포트폴리오 최적화에는 지난 1년간 거래 이력이 중복되는 최소 두 개의 티커가 필요합니다. 모든 티커가 유효하고 충분한 이력이 있는지 확인하세요.
필드 매핑
| 필드 | 경로 | 비고 |
|---|---|---|
| 사용된 티커 | tickers | 일부 티커에 데이터가 없으면 입력과 다를 수 있음 |
| 가격 행 수 | price_rows | 중복 거래일 수 |
| 동일 가중치 | equal_weight.weights | {ticker: 십진수} — %로 변환하려면 100을 곱함 |
| 동일 수익률 | equal_weight.annual_return_pct | 이미 % 단위 |
| 동일 변동성 | equal_weight.annual_volatility_pct | 이미 % 단위 |
| 동일 샤프 | equal_weight.sharpe_ratio | 연간 기준, 무위험 수익률 = 5% |
| 동일 VaR | equal_weight.var_95_daily_pct | 이미 %, 일간 |
| 최적 가중치 | optimal.weights | {ticker: 십진수} — %로 변환하려면 100을 곱함 |
| 최적 수익률 | optimal.annual_return_pct | 이미 % 단위 |
| 최적 변동성 | optimal.annual_volatility_pct | 이미 % 단위 |
| 최적 샤프 | optimal.sharpe_ratio | 연간 기준, 무위험 수익률 = 5% |
| 최적 VaR | optimal.var_95_daily_pct | 이미 %, 일간 |
| 최적화 성공 여부 | optimal.optimizer_success | 불리언 |
| 최적화 메시지 | optimal.optimizer_message | success = false인 경우에만 관련 있음 |
| 상관관계 행렬 | correlation_matrix | 중첩 딕셔너리 {ticker: {ticker: corr}} |
| 포트폴리오 VaR | portfolio_var_95_daily_pct | 최적 포트폴리오 일간 VaR, 이미 % 단위 |
5단계 — 해석 및 제시
가중치
십진수 가중치를 백분율로 변환합니다 (가중치 * 100, 소수점 첫째 자리).
최적 포트폴리오에서 어떤 가중치가 0.0%라면, 최적화 프로그램이 해당 자산을 제외했음을 알립니다 (충분하지 못한 수익률 또는 다른 자산과의 높은 상관관계).
샤프 비율
- < 0: 포트폴리오 수익률이 무위험 수익률(5%)보다 낮음; 구성을 재고해야 함.
- 0~1: 낮은 위험 조정 수익률.
- 1~2: 양호.
-
2: 우수.
동일 가중치 샤프와 최적 샤프를 비교합니다. 최적 샤프가 더 높다면 집중된 가중치가 정당화됩니다. 유사하다면 (차이 < 0.1), 동일 가중치 포트폴리오가 거의 동등하게 효율적이며 리밸런싱이 더 간단합니다.
상관관계 행렬
쌍별 상관관계를 해석합니다:
-
0.80: 높은 상관관계 — 이 두 자산은 거의 함께 움직입니다; 둘 다 보유해도 분산 효과가 거의 없습니다.
- 0.50~0.80: 중간 상관관계 — 어느 정도 동반 움직임, 부분적인 분산 효과.
- < 0.30: 낮은 상관관계 — 좋은 분산 투자 쌍.
- 0에 가깝거나 음수: 강력한 분산 효과.
가장 상관관계가 높은 쌍과 가장 낮은 쌍을 식별하여 설명에 언급합니다.
VaR
95% 신뢰 수준의 일간 VaR: 20 거래일 중 최악의 하루에, 포트폴리오는 역사적으로 약 {portfolio_var_95_daily_pct}% 손실을 입었습니다. 대략적인 연간 추정치는 도움이 될 경우에만 제공: 일간 VaR에 √252 ≈ 15.9를 곱하여 연간 VaR를 근사합니다 (이는 대략적인 근사치입니다).
최적화 실패
optimal.optimizer_success = false인 경우:
최적화 프로그램이 수렴하지 않았습니다 ({optimal.optimizer_message}). 최적 가중치가 동일 가중치로 대체되었습니다 — "최적" 열을 동일 가중치로 간주하세요.
포트폴리오 내 인도 주식
티커가 .NS 또는 .BO로 끝나는 경우, INR 표시 자산이 USD 기반 투자자에게 환 위험을 초래한다는 점을 알립니다. 상관관계 행렬은 현지 통화 수익률을 반영하며 INR/USD 변동성을 포착하지 않습니다.
6단계 — 추천
데이터를 제시한 후, 2~3문장의 추천을 제공합니다:
- 동일 가중치 또는 최적 가중치 중 어떤 것을 사용할지와 그 이유를 명시합니다 (샤프 비교).
- 최적 포트폴리오의 상위 1~2개 보유 종목과 그 가중치를 결정하는 요인을 언급합니다.
- 분산 투자 우려 사항 (높은 상관관계 쌍) 또는 환 위험 고려 사항이 있으면 언급합니다.
출력
# 포트폴리오 분석 — {쉼표로 구분된 티커 목록}
가격 이력: {price_rows}개의 중복 거래일 (≈ {price_rows/252:.1f}년)
---
## 배분 비교
| 티커 | 동일 가중치 | 최적 가중치 |
|----------|-------------|----------------|
| {ticker} | {ew*100:.1f}% | {ow*100:.1f}% |
| … | … | … |
---
## 포트폴리오 지표
| 지표 | 동일 가중치 | 최적 (최대 샤프) |
|--------------------------|-------------|----------------------|
| 예상 연간 수익률 | {eq_ret}% | {opt_ret}% |
| 연간 변동성 | {eq_vol}% | {opt_vol}% |
| 샤프 비율 | {eq_sh} | {opt_sh} |
| VaR (95%, 1일) | {eq_var}% | {opt_var}% |
{최적화 성공 = false인 경우:
> ⚠ 최적화 프로그램이 수렴하지 않았습니다 ({optimizer_message}) — 최적 가중치는 동일 가중치와 같습니다.}
---
## 상관관계 행렬
| 티커 | {t1} | {t2} | … |
|--------|------|------|---|
| {t1} | 1.00 | … | … |
| … | … | … | … |
**가장 상관관계가 높은 쌍:** {t_a} / {t_b} (상관계수: {corr:.2f}) — 분산 효과 제한적.
**가장 상관관계가 낮은 쌍:** {t_c} / {t_d} (상관계수: {corr:.2f}) — 가장 강력한 분산 효과.
---
## 추천
{2~3문장: 동일 vs 최적 선택, 주요 보유 종목 근거, 분산 투자 또는 환 위험 주의 사항.}
{.NS/.BO 티커가 있는 경우:
> ⚠ 인도 주식 ({목록})은 INR로 표시됩니다. 상관관계 행렬은 현지 통화 수익률을 반영하며 USD 기반 투자자의 INR/USD 환율 위험을 포착하지 않습니다.}
오류 복구
| 상황 | 조치 |
|---|---|
결과에 최상위 error가 있음 | 문제를 설명하고, 사용자에게 티커를 확인하고 다시 시도하도록 요청 |
tickers 목록에서 티커가 제외됨 | 해당 티커에 충분하지 않거나 중복되지 않은 가격 이력이 있음을 알림 |
optimizer_success = false | 동일 가중치로 대체됨을 설명하고, 여전히 지표 표시 |
단일 .NS/.BO 티커 | 환 위험을 알리고, 상관관계 행렬에 평소와 같이 표시 |