cuFOLIO 스킬은(는) 무엇을 하나요?
목적
NVIDIA 가속 Mean-CVaR 최적화를 사용하여 정량적 포트폴리오를 구축하고 분석합니다. cuFOLIO를 사용하여 수익률을 계산하고, KDE 시나리오를 생성하며, cuOpt GPU 솔버로 할당을 해결하고, 효율적 프론티어를 추적하며, 포트폴리오를 백테스트하고, 가격 데이터로부터 리밸런싱 워크플로우를 실행합니다.
사용 시기
이 스킬은 다음 작업에 사용합니다.
- 주가로부터 Mean-CVaR 포트폴리오 구축 또는 최적화
- 하방 CVaR 리스크를 통제하면서 티커별 가중치 할당
- 포트폴리오 유니버스에 대한 효율적 프론티어 플롯 또는 검사
- 위험 회피도별 가중치 테이블 생성
- 최적화된 포트폴리오를 벤치마크와 백테스트
- 일정 또는 드리프트 트리거에 따른 포트폴리오 리밸런싱
- S&P 500, S&P 100, Dow 30 또는 사용자 제공 가격 데이터셋에서 워크플로우 실행
일반적인 트리거 구문으로는 "내 포트폴리오 최적화", "CVaR 포트폴리오 구축", "이 티커에 cuFOLIO 사용", "cuOpt으로 해결", "효율적 프론티어 플롯", "위험 회피도별 가중치 표시", "이 할당 백테스트", "월별 리밸런싱", "CVaR로 내 보유 분석", "할당 비교", "하방 리스크 감소", "할당 구성", "할당 옵션 평가", "내 보유 스트레스 테스트", "하방 리스크 노출 평가", "가중치 상한 하 보유 검토", "벤치마크 포트폴리오 비교", "CVaR 시나리오 시뮬레이션", "포트폴리오 리스크 선별", "제약 조건 하 보유 최적화", "저위험 할당 찾기" 등이 있습니다.
일반 재무 요약, 주가 예측, 신경망 훈련, 차량 경로 최적화 또는 비포트폴리오 최적화에는 사용하지 마십시오.
전제 조건
cufolio패키지가 설치된 Python 환경- cuOpt 및 cuML이 설치된 NVIDIA GPU 런타임
- 호스트와 일치하는 CUDA 익스트라, 예:
uv sync --extra cuda12또는uv sync --extra cuda13 cp.CUOPT를 노출하는cvxpy- 기본 가격 CSV를 다운로드해야 하는 경우 첫 실행 시 네트워크 액세스
설정
이 스킬은 설치된 cufolio 패키지를 구동합니다. 준비된 환경은 Brev 런처블 또는 일치하는 CUDA 익스트라를 설치한 후 NVIDIA-AI-Blueprints/cuFOLIO에서 얻을 수 있습니다.
패키지화된 에이전트/평가 샌드박스에서 cufolio는 별도로 게시된 휠이 아닌 PYTHONPATH를 통해 사용할 수 있습니다. 누락되었다고 선언하기 전에 python -c "import cufolio"로 로컬 패키지를 확인하십시오. pip install cufolio를 하지 말고, cuFOLIO 워크플로우를 처음부터 다시 구현하지 말며, 패키지 API를 일반 pandas/scipy/cvxpy 포트폴리오 코드로 대체하지 마십시오.
구체적인 구현 세부 사항은 references/workflows/agent_recipes.md를 진실 공급원으로 사용하십시오. 여기에는 가격 로드, 수익률 준비, cuOpt으로 해결, 25포인트 프론티어 구축, 동일 가중치 대비 백테스트, 리밸런서 호출을 위한 정확한 작동 형태가 포함되어 있습니다.
기본 데이터셋은 data/stock_data/sp500.csv입니다. gitignore에 포함되어 있습니다. 첫 번째 다운로드 전에 사용자에게 cuFOLIO/yfinance 데이터 헬퍼를 통해 공개 시장 데이터를 가져온다고 알리고 확인을 요청합니다.
import cvxpy as cp
from cufolio.cvar_parameters import CvarParameters
from cufolio.utils import download_data
download_data("data/stock_data", datasets=["sp500"])
SOLVER_SETTINGS = {"solver": cp.CUOPT, "verbose": False, "solver_method": "PDLP"}
cvar_params = CvarParameters(
w_min=0.0, w_max=1.0,
c_min=0.0, c_max=0.0,
risk_aversion=1.0, confidence=0.95,
)
지침
실행 전에 적용되는 기본값을 간략히 명시한 후 다음 가드레일을 사용합니다.
data/stock_data/sp500.csv를 로드합니다. 파일이 없으면cufolio.utils.download_data로sp500을 다운로드하기 전에 사용자에게 확인을 요청합니다. 가격 데이터를 글로브, 대체 또는 조작하지 마십시오.- 사용자 CSV를 해결 전에 검증합니다. 날짜 형식 인덱스 또는 첫 번째 날짜 열, 숫자 티커 열, 날짜 필터링 후 최소 60개 행, 그리고 하나 이상의 요청된 티커가 필요합니다. 사용자가 시작/종료 날짜를 제공하면 수익률 계산 전에 가격 DataFrame을 슬라이스하고 유지된 날짜 범위를 보고합니다. 수익률이 계산되기 전에 가격 DataFrame에서 티커를 필터링합니다.
regime_dict는 티커 필드를 사용하지 않습니다. utils.calculate_returns(...)로 LOG 수익률을 계산합니다.cvar_utils.generate_cvar_data(...), KDE 및KDESettings(device="GPU")를 사용하여 시나리오를 생성합니다.- 명시적인
w_min및w_max로CvarParameters를 정의합니다. 일반적인 "최적 포트폴리오 구축" 요청의 경우c_min=0.0및c_max=0.0을 설정하여 결과가 100% 현금 대신 완전 투자되도록 합니다. - 수익률 딕셔너리에서 직접
cvar_optimizer.CVaR(returns_dict, cvar_params)를 구축합니다. 티커, 시나리오 배열, 평균 및 공분산을 cuFOLIO 헬퍼에서 반환된 형태로 유지합니다. - NVIDIA cuOpt으로만 해결합니다. 해결 전에
hasattr(cp, "CUOPT")및str(cp.CUOPT) in {str(s) for s in cp.installed_solvers()}를 확인합니다. 모든 단일 해결 또는 루프 프론티어 해결에SOLVER_SETTINGS를 전달합니다. CLARABEL, SCS, ECOS 또는 다른 CPU 솔버로 절대 폴백하지 마십시오. cuOpt이 없으면 GPU/cuOpt 런타임이 누락되었음을 보고하고 CPU 결과를 조작하지 마십시오. - 사용자 정의 제약 조건의 경우 사용자 요청을
CvarParameters에 매핑합니다. 가중치 상한은w_min/w_max, 위험 선호도는risk_aversion, 신뢰 수준은confidence, 현금 허용은c_max, 카디널리티는 패키지가 워크플로우에 대해 명시적인 자산 수 제약 조건을 노출하는 경우에만 매핑합니다. 제약 조건이 충돌하는 경우(예: 요청된 티커 수에 투자하기에는 최대 가중치가 너무 낮은 경우) 충돌을 설명하고 추측 대신 제약 조건을 완화하도록 요청합니다. - 사용자가 백테스트를 위한 벤치마크를 생략하면 동일한 티커에 대해 동일 가중치 포트폴리오를 사용합니다. 사용자가 제약 조건을 생략하면 기본 테이블 값을 유지하고 중요한 가정을 해결 전에 간략히 다시 설명합니다.
- 할당별로 정렬된 가중치, 현금 가중치, 기대 수익률, CVaR, 솔버 레이블(
cuOpt GPU) 및 요청된 프론티어 그림, 가중치 테이블, 백테스트 메트릭 또는 리밸런싱 일정을 제공합니다. 테이블의 경우 소수 및 백분율 가중치로 열 또는 행에 티커를 포함합니다. 플롯의 경우 다시 그리지 않고 반환된 cuFOLIO 그림을 유지합니다. - 보고서 수준의 답변의 경우 요청된 워크플로우가 실제로 실행되었음을 증명하는 증거를 포함합니다. 효율적 프론티어의 경우
len(results_df)를 명시하고 요청된ra_num(사용자가 지정하지 않는 한 25)을 사용합니다. 가중치 테이블의 경우results_df["weights"]를 티커 열로 확장하고cash및risk_aversion을 포함합니다. 백테스트의 경우 최적화 및 벤치마크 포트폴리오 모두에 대해mean portfolio return,sharpe,sortino및max drawdown을 포함합니다. 리밸런싱의 경우results_dataframe,re_optimize_dates및cumulative_portfolio_value의 테일을 포함합니다.
표준 워크플로우 골격
긍정적인 cuFOLIO 작업을 이 형태에서 시작하고 요청된 출력만 조정합니다. 완전한 복사 가능한 함수는 사용자 정의 코드를 작성하기 전에 references/workflows/agent_recipes.md를 읽으십시오.
import cvxpy as cp
import pandas as pd
from cufolio import backtest, cvar_optimizer, cvar_utils, rebalance, utils
from cufolio.cvar_parameters import CvarParameters
from cufolio.portfolio import Portfolio
from cufolio.settings import KDESettings, ReturnsComputeSettings, ScenarioGenerationSettings
if not hasattr(cp, "CUOPT") or str(cp.CUOPT) not in {str(s) for s in cp.installed_solvers()}:
raise RuntimeError("cuOpt GPU solver가 필요합니다. CPU 솔버를 대체하지 마십시오.")
SOLVER_SETTINGS = {"solver": cp.CUOPT, "verbose": False, "solver_method": "PDLP"}
prices = utils.get_input_data("data/stock_data/sp500.csv")
returns_dict = utils.calculate_returns(
prices,
regime_dict=None,
returns_compute_settings=ReturnsComputeSettings(return_type="LOG"),
)
returns_dict = cvar_utils.generate_cvar_data(
returns_dict,
ScenarioGenerationSettings(
fit_type="kde",
kde_settings=KDESettings(device="GPU"),
),
)
cvar_params = CvarParameters(
w_min=0.0,
w_max=1.0,
c_min=0.0,
c_max=0.0,
risk_aversion=1.0,
confidence=0.95,
)
optimizer = cvar_optimizer.CVaR(returns_dict, cvar_params)
result, optimal_portfolio = optimizer.solve_optimization_problem(
solver_settings=SOLVER_SETTINGS,
print_results=False,
)
효율적 프론티어 또는 가중치 테이블의 경우 다음을 호출합니다.
results_df, fig, ax = cvar_utils.create_efficient_frontier(
returns_dict,
cvar_params,
SOLVER_SETTINGS,
ra_num=25,
show_plot=False,
show_discretized_portfolios=False,
benchmark_portfolios=False,
print_portfolio_results=False,
)
weights_table = pd.DataFrame(results_df["weights"].tolist(), index=results_df.index)
벤치마크 백테스트의 경우 해결된 할당을 Portfolio(name="cuOpt Optimal", tickers=returns_dict["tickers"], weights=optimal_portfolio.weights, cash=optimal_portfolio.cash)로 래핑하고 동일한 returns_dict["tickers"]에 대해 동일 가중치 Portfolio를 생성한 다음 backtest.portfolio_backtester(..., test_method="historical").backtest_against_benchmarks(...)를 사용합니다. 백테스터는 (backtest_results, ax)를 반환합니다.
월별 리밸런싱의 경우 먼저 가격 DataFrame을 CSV 경로에 씁니다. re_optimize_criteria={"type": "drift_from_optimal", "threshold": 0, "norm": 1}로 rebalance.rebalance_portfolio(dataset_directory=<csv_path>, ...)를 인스턴스화하고 re_optimize(transaction_cost_factor=..., plot_title="Monthly Rebalancing")을 호출합니다. 리밸런서는 (results_dataframe, re_optimize_dates, cumulative_portfolio_value)를 반환합니다.
데이터 및 기본값
| 설정 | 기본값 |
|---|---|
| 데이터셋 | data/stock_data/sp500.csv |
| 날짜 범위 | 사용 가능한 전체 범위 |
| 포트폴리오 유형 | 롱 온리 |
| 최대 가중치 | 지정되지 않은 경우 없음 |
| 위험 회피도 | 1.0 |
| 신뢰 수준 | 0.95 |
| 시나리오 방법 | GPU의 KDE |
| 솔버 | PDLP를 사용하는 cuOpt GPU |
| 리밸런싱 | 요청되지 않은 경우 없음 |
기본 S&P 500 파일은 과거 스냅샷이며 현재 구성 요소가 누락될 수 있습니다. 사용자 제공 CSV는 utils.get_input_data와 호환되는 날짜 인덱스 가격 테이블과 티커 열이어야 합니다. 요청된 티커가 없으면 이를 드롭하고 누락을 보고하며 사용자가 명시적으로 다른 데이터를 가져오도록 요청하지 않는 한 사용 가능한 열로 계속 진행합니다.
주요 API
포트폴리오 수학이나 시뮬레이션 루프를 다시 구현하는 대신 패키지 API를 사용하십시오. cuFOLIO 헬퍼는 평평한 객체를 반환합니다. returns_dict에는 returns, mean, covariance 및 tickers와 같은 키가 있습니다. returns_dict["regime_1"]로 인덱싱하지 마십시오. solve_optimization_problem(...)는 중첩된 결과 딕셔너리가 아닌 (result_row, portfolio)를 반환합니다.
- 수익률:
utils.calculate_returns(input_dataset, regime_dict, returns_compute_settings). - 체제 필터:
regime_dict는None또는{"name": "...", "range": ("YYYY-MM-DD", "YYYY-MM-DD")}입니다. 체제 이름으로 키가 지정되지 않으며 티커를 포함하지 않습니다. - 시나리오:
cvar_utils.generate_cvar_data(returns_dict, scenario_generation_settings). - 최적화기:
cvar_optimizer.CVaR(returns_dict, cvar_params). - 해결:
result_row, portfolio = cvar_problem.solve_optimization_problem(solver_settings=SOLVER_SETTINGS, print_results=False). - 효율적 프론티어:
cvar_utils.create_efficient_frontier(returns_dict, cvar_params, solver_settings=SOLVER_SETTINGS, ra_num=25). 반환된results_df에는 메트릭,weights딕셔너리 열 및cash가 포함됩니다. - 포트폴리오:
Portfolio(name="", tickers=None, weights=None, cash=0.0, time_range=None); 해당 티커에 정렬된 티커 및 평평한 배열형weights를 전달합니다. - 백테스트: 최적화된 할당 및 각 벤치마크에 대해
portfolio.Portfolio객체를 생성합니다. 동일 가중치 벤치마크의 경우1 / len(tickers)의 가중치와cash=0.0을 사용한 다음backtest.portfolio_backtester(test_portfolio, returns_dict, risk_free_rate=0.0, test_method="historical", benchmark_portfolios=[...]).backtest_against_benchmarks(...)를 호출합니다. - 리밸런싱:
rebalance.rebalance_portfolio(...)는dataset_directory가 DataFrame이 아닌 CSV 경로여야 합니다.re_optimize(...)를 호출합니다.(results_dataframe, re_optimize_dates, cumulative_portfolio_value)를 반환합니다. - 설정 모델:
ReturnsComputeSettings,ScenarioGenerationSettings,KDESettings,ApiSettings및CvarParameters.
예제
- "S&P 500에서 최적 포트폴리오 구축": 가격 로드, LOG 수익률 계산, GPU KDE 시나리오 생성, 롱 온리 완전 투자
CvarParameters설정, cuOpt으로 해결, 분산된 가중치 및 수익률/CVaR 보고. - "효율적 프론티어 플롯":
create_efficient_frontier(...)호출,results_df반환, 요청된 대로 그림 표시 또는 저장. - "위험 회피도별 가중치 제공":
results_df["weights"]를 자산별 테이블로 확장. - "동일 가중치 대비 백테스트": 최적화 및 동일 가중치
Portfolio객체 구축, cuFOLIO 백테스터 사용, Sharpe, Sortino 및 최대 드로다운 보고. - "월별 리밸런싱 백테스트": 위 드리프트 트리거로
rebalance_portfolio구성,re_optimize(transaction_cost_factor=...)실행.
제한 사항
- cuOpt 및 cuML이 있는 NVIDIA GPU 필요. CPU 솔버는 의도적으로 허용되지 않습니다.
- CPU 전용 평가 컨테이너는 라우팅, 데이터 처리 및 보고 동작을 여전히 검증할 수 있지만 유효한 cuOpt 해결을 생성할 수 없습니다. 이 경우 누락된 GPU/cuOpt 런타임을 명시적으로 보고합니다.
- 기본 가격 데이터는 과거 스냅샷이며 현재 구성 요소가 누락될 수 있습니다.
- 사용자가 CSV를 제공하지 않는 한 첫 실행 데이터셋 다운로드는 네트워크 액세스에 따라 다릅니다.
문제 해결
- 기본 CSV 누락 또는
FileNotFoundError: cuFOLIO가download_data("data/stock_data", datasets=["sp500"])로 공개 시장 데이터를 가져온다고 설명합니다. 사용자 확인 후에만 실행합니다. SolverError또는cp.CUOPT누락: 호스트와 일치하는 CUDA 익스트라를 설치하고python -c "import cvxpy as cp; print(hasattr(cp, 'CUOPT'), cp.installed_solvers())"로 확인합니다.