목차

1. AI 자동 투자에서의 중요한 점 — 전략과 백테스팅
2. 시스템 구조와 현재 워크플로우
3. 전략 소개
4. 사용한 API와 데이터 소스
5. 발전 방향 — OpenClaw 자동화

1. AI 자동 투자에서의 중요한 점 — 전략과 백테스팅

"AI한테 투자해줘~" 라고 하면 될 것 같지만, 현실은 다르다. 작동 안 할 확률이 높다.

핵심은 좋은 전략을 찾고, 백테스팅으로 검증하는 것이다. AI가 잘하는 건 코드를 빠르게 짜는 것이지, 마법처럼 수익을 내는 것이 아니다.

내가 한 과정:

1. 인터넷/논문에서 검증된 퀀트 전략들을 조사
2. Claude Code로 백테스팅 프레임워크를 구축
3. 수십 개의 전략 변형을 배치로 돌려 비교
4. Sharpe ratio, CAGR, MaxDD 기준으로 최적 전략 선별
5. 선별된 전략을 실전 투자 시스템에 배포

요즘에는 인터넷에서 쉽게 접할 수 있는 전략이 정말 많다. 중요한 것은 그걸 자기 상황에 맞게 파라미터를 조정하고, 과거 데이터로 검증하는 과정이다.

2. 시스템 구조와 현재 워크플로우

프로젝트는 크게 두 모듈로 나뉜다:

quanty/
├── backtest/          ← 백테스팅 프레임워크
│   ├── src/quanty/
│   │   ├── data/      ← 데이터 소스 (Yahoo, FRED, Upbit)
│   │   ├── strategy/  ← 전략 구현체들
│   │   ├── engine/    ← 백테스트 엔진, 포트폴리오, 메트릭스
│   │   └── report/    ← 리포트 생성
│   └── strategies/    ← TOML 설정 파일들
│
├── invest/            ← 실전 투자 시스템
│   ├── src/invest/
│   │   ├── broker/    ← KIS(한국투자증권), Upbit 브로커
│   │   ├── executor/  ← 매매 실행 엔진
│   │   ├── scheduler/ ← APScheduler 기반 스케줄러
│   │   ├── notify/    ← Telegram 알림
│   │   └── strategy/  ← 백테스트 전략을 실전에 연결하는 어댑터
│   └── docker-compose.yml

워크플로우

[백테스팅]
전략 TOML 작성 → 백테스트 엔진 실행 → 메트릭스 비교 → 최적 전략 선정
                                                              ↓
[실전 투자]
스케줄러 (매주 화요일 10AM ET) → 시그널 생성 → 리스크 체크 → 매매 실행 → Telegram 알림

실전 매매 흐름 (상세):

1. MultiStrategyRunner가 각 전략의 시그널을 생성
2. 전략별 가중치를 배분 비율에 따라 병합: merged_weight[sym] = Σ(전략_weight × allocation)
3. 리스크 체크 통과 여부 확인
4. 마켓 시간 확인 (장 마감이면 다음 개장까지 대기)
5. 브로커별 독립 포트폴리오로 매매 계산:
   • KIS: SPY/GLD/BND의 USD 주식 매매
   • Upbit: BTC의 KRW 암호화폐 매매
6. 매도 먼저 실행 → 매수 실행 (시장가 주문)
7. Telegram으로 결과 알림 (포트폴리오 현황, 목표 비중, 체결 내역, 백테스트 벤치마크 비교)

멀티 전략 지원

invest/strategies/live.toml에서 여러 전략을 조합할 수 있다:

[[strategies]]
config = "strategies/macro_rotation_weekly.toml"
initial_balance = 3000    # 비율: 3000/(3000+1000) = 75%
rebalance_weekday = 1     # 화요일

[[strategies]]
config = "strategies/zscore_btc.toml"
initial_balance = 1000    # 25%
rebalance_weekday = 1

initial_balance는 실제 금액이 아니라 비율 계산용이다. 실제 매매는 브로커의 실시간 잔고를 기준으로 한다.

3. 전략 소개

A. Macro Rotation (매크로 로테이션)

핵심 아이디어: 거시경제 지표를 feature로 사용해 자산별 수익률을 예측하고, 포트폴리오를 자동 배분한다.

작동 방식:

1. 과거 4년 데이터로 각 자산의 N일 후 수익률을 학습
2. 현재 매크로 지표를 입력하여 각 자산의 미래 수익률을 예측
3. 양수 수익률이 예측된 자산에만 역변동성 가중으로 배분
4. 예측 수익률이 모두 음수면 → 전액 현금

B. Z-Score (크립토 트렌드 팔로잉)

핵심 아이디어: 가격의 Z-Score를 계산하여 추세를 추종한다. 상승 추세에 진입, 하락 전환 시 퇴장.

히스테리시스 설계로 빈번한 매매를 방지한다. 낮은 승률(~47%)이지만, 평균 수익 >> 평균 손실로 양의 기대값을 가진다.

C. Macro + Z-Score 하이브리드

핵심 아이디어: 매크로 로테이션(ETF)과 Z-Score(크립토)를 결합한다.

매크로 부분은 월간/주간 리밸런싱, 크립토 부분은 Z-Score 기반 일간 신호.

D. Dual Momentum (듀얼 모멘텀)

핵심 아이디어: 절대 모멘텀 + 상대 모멘텀으로 크립토를 선별한다.

1. 절대 모멘텀: 21일 수익률 > 0인 코인만 통과 (추세 필터)
2. 상대 모멘텀: 통과한 코인 중 상위 2개 선택
3. 선택된 코인에 균등 배분, 통과한 코인이 없으면 → 100% 현금

배치 백테스트 비교

모든 전략을 한 번에 비교할 수 있다:

uv run python -m quanty --batch strategies/all.toml

결과는 Sharpe ratio 기준 내림차순으로 정렬되어 출력되고, results/comparison_<timestamp>.txt에 자동 저장된다.

================================================================
  STRATEGY COMPARISON
================================================================
          Strategy   CAGR  Sharpe  Sortino   MaxDD    Vol  Calmar  Trades  Final($)
----------------------------------------------------------------
     macro_zscore  24.10%    0.26     0.10  -23.78%  2.52%    1.01    2602  465,406
   macro_rotation  11.22%    0.85     1.34  -18.24%  9.01%    0.62      73  198,450
              ...
================================================================
  (Sorted by Sharpe ratio, descending)

4. 사용한 API와 데이터 소스

데이터 수집

FRED 공식 API:

• 무료 API 키 발급: https://fred.stlouisfed.org/docs/api/api_key.html
• Rate limit: 120 req/min (충분)
• 처음에 CSV 스크래핑 엔드포인트를 썼다가 502/504 에러로 고생 → 공식 API로 전환하니 안정적
• PostgreSQL에 캐시하여 한 번 받은 데이터는 다시 API 호출 불필요 (gap-fill 패턴)

심볼 라우팅:

"FRED:VIXCLS"    → FRED 공식 API → PostgreSQL 캐시
"UPBIT:BTC:60m"  → Upbit REST API → PostgreSQL 캐시
"SPY"            → Yahoo Finance  → Parquet 파일 캐시

실전 매매 브로커

KIS: 실전/모의투자 계정 모두 지원 (KIS_ACCOUNT_TYPE=01 실전, 03 모의)

Telegram 알림

리밸런싱 시 알림 내용:

• 포트폴리오 총 가치 (KIS USD + Upbit KRW→USD 환산)
• 목표 비중과 예측 수익률
• 실행된 매매 내역
• 백테스트 벤치마크 비교 (CAGR, Sharpe, MaxDD, 월간 승률)

매일 4:30 PM ET에 일간 스냅샷도 전송한다.

5. 배포 구조

Docker Compose로 배포한다:

services:
  db:
    image: postgres:16-alpine     # 매매 기록, 시그널 저장
  app:
    build: invest/Dockerfile      # Python 3.13 + uv
    env_file: .env.deploy         # API 키, 브로커 설정
    restart: unless-stopped       # 자동 재시작

스케줄러 (APScheduler):

• 리밸런싱: 매주 화요일 10:00 AM ET (뉴욕 시간)
• 일간 스냅샷: 평일 4:30 PM ET
• KIS 토큰 갱신: 12시간마다
• 헬스체크: 5분마다
• 장 마감 시: 다음 개장(9:30 AM ET)까지 자동 대기

6. 발전 방향 — OpenClaw 자동화

현재는 직접 전략을 찾아서 구현하고 백테스트하는 구조다. 이걸 OpenClaw로 자동화하면 어떨까?

구상하는 파이프라인

[Daily Quant Digest]         ← 매일 퀀트 리서치/뉴스레터 수집
        ↓
[전략 추출]                  ← OpenClaw가 논문/기사에서 전략 로직 추출
        ↓
[자동 코딩]                  ← 백테스팅 코드 자동 생성 (TOML + Strategy 클래스)
        ↓
[백테스트 실행]              ← 기존 프레임워크에서 자동 실행
        ↓
[결과 필터링]                ← Sharpe > 0.8, MaxDD < -25% 등 기준으로 선별
        ↓
[Telegram 알림]              ← "유의미한 전략 발견!" 사용자에게 통지

OpenClaw Cron Job 설계

0 6 * * * /openclaw/daily_quant_digest.py     # 매일 새벽 6시
0 7 * * * /openclaw/extract_strategies.py      # 전략 추출
0 8 * * * /openclaw/auto_backtest.py           # 자동 백테스트
0 9 * * * /openclaw/notify_findings.py         # 결과 알림

기대 효과:

• 매일 새로운 전략을 자동으로 발굴하고 검증
• 사람이 할 일: 알림을 보고 최종 판단만 하면 됨
• 점점 더 많은 전략이 축적되면서 포트폴리오 다각화 가능

추가 발전 방향

1. 실시간 모니터링 대시보드: Grafana + PostgreSQL 메트릭스
2. 슬리피지/거래비용 정교화: 백테스트의 현실성 향상
3. 옵션/선물 헤징: 하락장 대비 자동 헤징 전략
4. 멀티 마켓 확장: 한국 주식, 일본 ETF 등

마무리

Claude Code로 하루 만에 백테스팅 프레임워크부터 실전 자동매매까지 구축했다. 핵심은:

1. 전략이 먼저다 — AI는 도구일 뿐, 검증된 전략 없이는 의미 없다
2. 백테스팅은 필수다 — 과거에 안 되는 전략이 미래에 될 리 없다
3. 자동화가 핵심이다 — 감정 개입 없이 룰 기반으로 매매

다음 단계는 OpenClaw로 전략 발굴 자체를 자동화하는 것이다. AI가 매일 새로운 전략을 찾아서 검증하고, 유의미한 결과만 알려주는 시스템. 투자의 미래가 이런 방향이지 않을까.

Built with Claude Code + OpenClaw Tech Stack: Python 3.13, uv, PostgreSQL, Docker, APScheduler, KIS API, Upbit API, FRED API, Telegram Bot API

Prerequisites

1. A Linux Server (Home server, VPS, or EC2) with Docker & Docker Compose installed.
2. A Domain Name (e.g., yourdomain.com).
3. A Cloudflare Account (Free tier is sufficient).

Step 1: Point Your Domain to Cloudflare

Skip this if your domain is already managed by Cloudflare.

1. Log in to the Cloudflare Dashboard and click "Domain registration".
2. Enter your root domain (e.g., yourdomain.com) and select the Free Plan.
3. Cloudflare will provide two Nameservers (e.g., bob.ns.cloudflare.com).
4. Log in to your domain registrar (Namecheap, GoDaddy, etc.).
5. Go to DNS Settings (or "Nameservers") and change "Default DNS" to "Custom DNS".
6. Paste the two Cloudflare nameservers and save.
7. Wait 15-30 minutes for Cloudflare to show the status as "Active".

Step 2: Set Up Cloudflare Tunnel (On Your Server)

This creates a secure link from your server to the internet without opening router ports.

2.1 Install cloudflared

Run this on your Linux server:

# Download and install the package
curl -L --output cloudflared.deb [https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb](https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb)
sudo dpkg -i cloudflared.deb

2.2 Authenticate and Create Tunnel

# Login (this gives you a URL to visit in your browser)
cloudflared tunnel login

# Create a new tunnel (Save the UUID output!)
cloudflared tunnel create langfuse-production

# Link your specific subdomain to the tunnel
# Replace <UUID> with your real ID from the previous command
cloudflared tunnel route dns <UUID> langfuse.yourdomain.com

2.3 Move Credentials to System Folder

The background service runs as root, so it needs the keys in /etc/cloudflared.

sudo mkdir -p /etc/cloudflared
sudo cp ~/.cloudflared/cert.pem /etc/cloudflared/
sudo cp ~/.cloudflared/*.json /etc/cloudflared/

2.4 Create Configuration File

Create the config file: sudo nano /etc/cloudflared/config.yml Paste the following content (Update <UUID> and hostname):

tunnel: <UUID>
credentials-file: /etc/cloudflared/<UUID>.json

ingress:
  - hostname: langfuse.yourdomain.com
    service: [http://127.0.0.1:3000](http://127.0.0.1:3000)
  - service: http_status:404

2.5 Start the Tunnel Service

# Install the system service
sudo cloudflared service install

# Start and enable it
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

Verification: Run sudo systemctl status cloudflared. It should be active (running).

Step 3: Configure Langfuse (Docker Compose)

You must update Langfuse to know its public URL, otherwise login will fail.

3.1 Edit docker-compose.yml

Open your file (nano docker-compose.yml) and update the langfuse-web service environment variables.

Crucial Changes:

1. NEXTAUTH_URL: Must match your https domain.
2. NEXT_PUBLIC_LANGFUSE_BASEURL: Must match your https domain.
3. Ports: Ensure it binds to 127.0.0.1 or 0.0.0.0.

Example Snippet:

  langfuse-web:
    image: docker.io/langfuse/langfuse:3
    restart: always
    depends_on: *langfuse-depends-on
    ports:
      - 3000:3000
    environment:
      <<: *langfuse-worker-env

      # --- NETWORK CONFIGURATION ---
      NEXTAUTH_URL: [https://langfuse.yourdomain.com](https://langfuse.yourdomain.com)
      NEXT_PUBLIC_LANGFUSE_BASEURL: [https://langfuse.yourdomain.com](https://langfuse.yourdomain.com)
      # -----------------------------

      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET:-mysecret}
      # ... (keep other existing variables) ...

3.2 Apply Changes

docker compose down
docker compose up -d

Step 4: Final Cloudflare Settings

1. Go to Cloudflare Dashboard > SSL/TLS.
2. Set encryption mode to Full. (Do not use "Flexible", it causes redirect loops).
3. Go to DNS. Ensure your langfuse CNAME record is Proxied (Orange Cloud icon).

Step 5: Verify

Visit https://langfuse.yourdomain.com.

• If it works on mobile but not desktop: It is a local DNS cache issue.
  • Fix: Change your computer's DNS to 1.1.1.1 or run sudo killall -HUP mDNSResponder (Mac) / ipconfig /flushdns (Windows).

준비물

폐쇄망에서는 단순히 LLM의 이름만으로 huggingface를 활용하여 모델을 불러오고, 관련 파이썬 패키지를 다운받는 것이 불가능하다. 그래서 아래의 준비물들이 필요하다.

1. LLM 폴더(혹은 gguf 파일)
2. 미리 다운받은 파이썬 패키지
3. 실행스크립트

1. LLM 폴더

따라서 오프라인에서 LLM을 로드하기 위해서는 LLM 폴더 자체 혹은 LLM gguf 파일이 필요하다. LLM 폴더는 huggingface 아이디를 활용하여 git clone으로 받을 수 있고, gguf 파일도 마찬가지로 huggingface web 상에서 다운로드 받을 수 있다.

모델 폴더 다운로드 예시

git clone https://huggingface.co/openai-community/gpt2 # root 폴더에 gpt2 모델 폴더 생성됨

2. 파이썬 패키지

파이썬 패키지도 폐쇄망이기 때문에 미리 다운로드를 받아야한다. pip download 를 활용하여 whl 파일로 저장해두고, LLM 로드 전 서버에 설치한다. 주의할 점은 아래의 패키지를 다운로드할 때 pip이 폐쇄망 내에서 사용할 파이썬 환경과 일치해야한다는 점이다.

VLLM 활용 파이썬 패키지 다운로드 예시

mkdir python-packages # 다운로드 받을 폴더 생성

pip download vllm -d ./python-packages # vllm 의존성 패키지를 생성한 폴더에 다운로드. 휠파일 생성

llama.cpp 활용 파이썬 패키지 다운로드 예시

mkdir python-packages

# vllm과 다르게 별도로 설치해줘야하는 의존성들이 있다
pip download \
  "llama-cpp-python[server]" \
  scikit-build-core \
  cmake \
  ninja \
  pydantic-core \
  setuptools \
  wheel \
  -d ./python-packages

3. 실행 스크립트

그리고 파이썬 패키지를 다운로드하고, python -m vllm..으로 시작하는 파이썬을 동작시킬 command line을 저장시킨 실행 스크립트가 있으면 좋다.

VLLM 활용 로드 (GPU)

VLLM은 GPU VRAM의 일정 부분을 할당하여 LLM을 로드하고, PagedAttention 알고리즘을 활용하여 메모리를 효율적으로 관리한다. 이를 통해 배치 처리를 최적화하고 더 많은 동시 요청을 처리할 수 있다.

1. 실행 스크립트 구성 {#vllm-ref}

원본 코드는 아래에서 확인 가능합니다.

실행 스크립트는 다음의 항목을 포함해야한다.

1. 폐쇄망 환경 설정
2. 파이썬 패키지 설치
3. python -m vllm.entrypoints.openai.api_server 실행

1.1. 폐쇄망 환경 설정

아래의 항목을 스크립트에 입력함으로써 huggingface가 인터넷에 접속하려는 시도를 막는다. 그리고 기타 환경변수를 설정해준다.

# start.sh
# Get the directory where this script is located
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export MODEL_PATH="${SCRIPT_DIR}/gemma-3-270m-it"

export HF_DATASETS_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
export HF_HUB_OFFLINE=1
export HF_DATASETS_CACHE="${SCRIPT_DIR}/.cache/huggingface/datasets"
export HF_HOME="${SCRIPT_DIR}/.cache/huggingface"
# ...

1.2. 파이썬 패키지 설치

아래의 항목을 스크립트에 입력함으로써 vllm 구동을 위한 패키지를 폐쇄망에 설치한다.

# start.sh
# ...
pip install --no-index --find-links "${SCRIPT_DIR}/python-packages" \
    vllm 

# ...

1.3. python... 실행문

아래의 항목을 스크립트 마지막에 입력함으로써 llm로드와 호스팅을 진행한다.

# start.sh
# ...
python -m vllm.entrypoints.openai.api_server \
    --host 0.0.0.0 \
    --port 8000 \
    --model "${MODEL_PATH}" \
    --gpu-memory-utilization 0.75 \
    --max-model-len 4096 \
    --trust-remote-code

llama.cpp 활용 로드 (CPU)

llama.cpp는 GPU 없이 CPU만으로도 LLM을 실행할 수 있도록 최적화된 라이브러리이다. GGUF 포맷의 양자화된 모델을 사용하여 메모리 사용량을 줄이고 CPU에서도 합리적인 속도로 추론을 수행할 수 있다.

1. 실행 스크립트 구성 {#llama-cpp-ref}

원본 코드는 아래에서 확인 가능합니다.

실행 스크립트는 다음의 항목을 포함해야한다.

1. 폐쇄망 환경 설정
2. 파이썬 패키지 설치
3. python -m llama_cpp.server 실행

1.1. 폐쇄망 환경 설정

아래의 항목을 스크립트에 입력함으로써 모델 경로와 기타 환경변수를 설정해준다.

# start.sh
# Get the directory where this script is located
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export MODEL_PATH="${SCRIPT_DIR}/gemma-3-1b-it-q4_0.gguf"
# ...

1.2. 파이썬 패키지 설치

아래의 항목을 스크립트에 입력함으로써 llama-cpp-python 구동을 위한 패키지를 폐쇄망에 설치한다.

# start.sh
# ...
pip install --no-index --find-links "${SCRIPT_DIR}/python-packages" \
    "llama-cpp-python[server]" 

# ...

1.3. python... 실행문

아래의 항목을 스크립트 마지막에 입력함으로써 llm로드와 호스팅을 진행한다.

# start.sh
# ...
python -m llama_cpp.server \
    --model "${MODEL_PATH}" \
    --host 0.0.0.0 \
    --port 8001 \
    --n_threads 4

주요 파라미터 설명:

• --n_threads: CPU 스레드 개수 (CPU 코어 수에 맞춰 조정)

테스트

간단하게 curl로 테스트해볼 수 있다.

VLLM 서버 테스트 (포트 8000)

# Health check
curl http://localhost:8000/health

# 모델 목록 조회
curl http://localhost:8000/v1/models

# Chat completion 테스트
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-3-270m-it",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

llama.cpp 서버 테스트 (포트 8001)

# Health check
curl http://localhost:8001/health

# Chat completion 테스트
curl -X POST http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

{{< anchor id="test-ref" >}}혹은 테스트를 위한 파이썬 파일을 생성하여 아래와 같이 테스트해볼 수 있다.

# VLLM 서버 테스트
python llm_test.py localhost 8000

# llama.cpp 서버 테스트
python llm_test.py localhost 8001

부록

uv가 설치되어있다는 전제로 uv를 활용해서 의존성 패키지를 설치했다.

#!/bin/bash

# Exit on error
set -e

# Get the directory where this script is located
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

echo "========================================="
echo "LLM Load & Host - vLLM (Closed Network)"
echo "========================================="
echo "Script Directory: ${SCRIPT_DIR}"
echo "========================================="
echo ""

# Step 1: Configure environment for offline mode
echo "[1/5] Configuring offline environment..."
export HF_DATASETS_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
export HF_HUB_OFFLINE=1
export HF_DATASETS_CACHE="${SCRIPT_DIR}/.cache/huggingface/datasets"
export HF_HOME="${SCRIPT_DIR}/.cache/huggingface"

# Configure UV for offline mode
export UV_NO_CACHE=1
export UV_OFFLINE=1
export UV_FIND_LINKS="${SCRIPT_DIR}/python-packages"

# Point to local model directory
export MODEL_PATH="${SCRIPT_DIR}/gemma-3-270m-it"

echo "✓ Environment configured for offline mode"
echo ""

# Step 2: Check if required directories exist
echo "[2/5] Checking required directories..."
if [ ! -d "${MODEL_PATH}" ]; then
    echo "ERROR: Model directory not found at ${MODEL_PATH}"
    exit 1
fi
echo "✓ Model directory found: ${MODEL_PATH}"

if [ ! -d "${SCRIPT_DIR}/python-packages" ]; then
    echo "ERROR: Python packages directory not found at ${SCRIPT_DIR}/python-packages"
    exit 1
fi
echo "✓ Python packages directory found"
echo ""

# Step 3: Check if UV is installed
echo "[3/5] Checking UV installation..."
if ! command -v uv &> /dev/null; then
    echo "ERROR: UV is not installed. Please install UV first."
    exit 1
fi
echo "✓ UV is installed: $(uv --version)"
echo ""

# Step 4: Initialize UV project and install dependencies
echo "[4/5] Setting up Python environment with UV..."

# Check if .venv already exists
if [ -d "${SCRIPT_DIR}/.venv" ]; then
    echo "Virtual environment already exists, skipping creation..."
else
    echo "Creating virtual environment..."
    cd "${SCRIPT_DIR}"
    uv venv
fi

# Install dependencies from local packages (including vLLM)
echo "Installing dependencies from local packages..."
cd "${SCRIPT_DIR}"

# Install packages using uv with local packages directory
# Note: vLLM doesn't need accelerate, only torch, transformers, vllm and dependencies
uv pip install --no-index --find-links "${SCRIPT_DIR}/python-packages" \
    vllm 

echo "✓ Dependencies installed from local packages"
echo ""

# Step 5: Start the vLLM server
echo "[5/5] Starting vLLM API server..."
echo "========================================="
echo "Server Configuration:"
echo "  - Model: ${MODEL_PATH}"
echo "  - Host: 0.0.0.0"
echo "  - Port: 8000"
echo "  - GPU Memory Utilization: 0.75"
echo "  - Max Model Length: 4096"
echo "========================================="
echo "Server will be accessible at:"
echo "  - Local: http://127.0.0.1:8000"
echo "  - Network: http://$(hostname -I | awk '{print $1}'):8000"
echo "  - API docs: http://$(hostname -I | awk '{print $1}'):8000/docs"
echo "  - OpenAI-compatible: http://$(hostname -I | awk '{print $1}'):8000/v1"
echo "========================================="
echo ""

# Run the vLLM server using UV
cd "${SCRIPT_DIR}"
uv run python -m vllm.entrypoints.openai.api_server \
    --host 0.0.0.0 \
    --port 8000 \
    --model "${MODEL_PATH}" \
    --gpu-memory-utilization 0.75 \
    --max-model-len 4096 \
    --trust-remote-code

uv가 설치되어있다는 전제로 uv를 활용해서 의존성 패키지를 설치했다.

#!/bin/bash

# Exit on error
set -e

# Get the directory where this script is located
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

echo "========================================="
echo "LLM Load & Host - llama.cpp (Closed Network)"
echo "========================================="
echo "Script Directory: ${SCRIPT_DIR}"
echo "========================================="
echo ""

# Step 1: Configure environment for offline mode
echo "[1/5] Configuring offline environment..."

# Configure UV for offline mode
export UV_NO_CACHE=1
export UV_OFFLINE=1
export UV_FIND_LINKS="${SCRIPT_DIR}/python-packages"

# Point to local model file
export MODEL_PATH="${SCRIPT_DIR}/gemma-3-1b-it-q4_0.gguf"

echo "✓ Environment configured for offline mode"
echo ""

# Step 2: Check if required files exist
echo "[2/5] Checking required files..."
if [ ! -f "${MODEL_PATH}" ]; then
    echo "ERROR: Model file not found at ${MODEL_PATH}"
    exit 1
fi
echo "✓ Model file found: ${MODEL_PATH}"

if [ ! -d "${SCRIPT_DIR}/python-packages" ]; then
    echo "ERROR: Python packages directory not found at ${SCRIPT_DIR}/python-packages"
    exit 1
fi
echo "✓ Python packages directory found"
echo ""

# Step 3: Check if UV is installed
echo "[3/5] Checking UV installation..."
if ! command -v uv &> /dev/null; then
    echo "ERROR: UV is not installed. Please install UV first."
    exit 1
fi
echo "✓ UV is installed: $(uv --version)"
echo ""

# Step 4: Initialize UV project and install dependencies
echo "[4/5] Setting up Python environment with UV..."

# Check if .venv already exists
if [ -d "${SCRIPT_DIR}/.venv" ]; then
    echo "Virtual environment already exists, skipping creation..."
else
    echo "Creating virtual environment..."
    cd "${SCRIPT_DIR}"
    uv venv
fi

# Install dependencies from local packages
echo "Installing dependencies from local packages..."
cd "${SCRIPT_DIR}"

# Install llama-cpp-python with server support
uv pip install --no-index --find-links "${SCRIPT_DIR}/python-packages" \
    "llama-cpp-python[server]"

echo "✓ Dependencies installed from local packages"
echo ""

# Step 5: Start the llama.cpp server
echo "[5/5] Starting llama.cpp API server..."
echo "========================================="
echo "Server Configuration:"
echo "  - Model: ${MODEL_PATH}"
echo "  - Host: 0.0.0.0"
echo "  - Port: 8001"
echo "  - Threads: 4"
echo "========================================="
echo "Server will be accessible at:"
echo "  - Local: http://127.0.0.1:8001"
echo "  - Network: http://$(hostname -I | awk '{print $1}'):8001"
echo "  - API docs: http://$(hostname -I | awk '{print $1}'):8001/docs"
echo "  - OpenAI-compatible: http://$(hostname -I | awk '{print $1}'):8001/v1"
echo "========================================="
echo ""

# Run the llama.cpp server using UV
cd "${SCRIPT_DIR}"
uv run python -m llama_cpp.server \
    --model "${MODEL_PATH}" \
    --host 0.0.0.0 \
    --port 8001 \
    --n_threads 4

#!/usr/bin/env python3
"""
Test client for vLLM OpenAI-compatible API
Usage: python test_vllm_client.py <server_ip> [port]
Example: python test_vllm_client.py 192.168.1.100 8000
"""

import sys
import requests
import json


def test_vllm_api(server_ip: str, port: int = 8000):
    """Test the vLLM OpenAI-compatible API endpoints."""
    base_url = f"http://{server_ip}:{port}"
    api_url = f"{base_url}/v1"

    print("=" * 60)
    print(f"Testing vLLM API at {base_url}")
    print("=" * 60)
    print()

    # Test 1: Health check
    print("[1/4] Testing health endpoint...")
    try:
        response = requests.get(f"{base_url}/health", timeout=5)
        response.raise_for_status()
        print("✓ Health check passed")
        try:
            # Try to parse as JSON
            health_data = response.json()
            print(json.dumps(health_data, indent=2))
        except:
            # If not JSON, just print the text
            print(f"Response: {response.text}")
    except Exception as e:
        print(f"✗ Health check failed: {e}")
        return False
    print()

    # Test 2: List models
    print("[2/4] Testing models endpoint...")
    try:
        response = requests.get(f"{api_url}/models", timeout=5)
        response.raise_for_status()
        print("✓ Models endpoint working")
        models = response.json()
        print(json.dumps(models, indent=2))

        # Get the model name for later use
        if models.get("data"):
            model_name = models["data"][0]["id"]
            print(f"\nUsing model: {model_name}")
        else:
            print("Warning: No models found")
            model_name = None
    except Exception as e:
        print(f"✗ Models endpoint failed: {e}")
        return False
    print()

    # Test 3: Chat completions (OpenAI-compatible)
    print("[3/4] Testing chat completions...")
    try:
        test_messages = [{"role": "user", "content": "Hello! How are you today?"}]
        print(f"Messages: {json.dumps(test_messages, indent=2)}")
        print("Generating... (this may take a moment)")

        response = requests.post(
            f"{api_url}/chat/completions",
            json={
                "model": model_name or "gemma-3-270m-it",
                "messages": test_messages,
                "max_tokens": 100,
                "temperature": 0.7,
            },
            timeout=60,
        )
        response.raise_for_status()

        result = response.json()
        print("✓ Chat completion successful")
        print()
        print("-" * 60)
        print("Request:")
        print(json.dumps(test_messages, indent=2))
        print("-" * 60)
        print("Response:")
        if "choices" in result and len(result["choices"]) > 0:
            message = result["choices"][0]["message"]["content"]
            print(message)
            print("-" * 60)
            print("Usage:", result.get("usage", {}))
        else:
            print(json.dumps(result, indent=2))
        print("-" * 60)
    except Exception as e:
        print(f"✗ Chat completion failed: {e}")
        return False
    print()

    # Test 4: Text completions (OpenAI-compatible)
    print("[4/4] Testing text completions...")
    try:
        test_prompt = "Once upon a time"
        print(f"Prompt: {test_prompt}")
        print("Generating... (this may take a moment)")

        response = requests.post(
            f"{api_url}/completions",
            json={
                "model": model_name or "gemma-3-270m-it",
                "prompt": test_prompt,
                "max_tokens": 50,
                "temperature": 0.7,
            },
            timeout=60,
        )
        response.raise_for_status()

        result = response.json()
        print("✓ Text completion successful")
        print()
        print("-" * 60)
        print("Prompt:", test_prompt)
        print("-" * 60)
        print("Completion:")
        if "choices" in result and len(result["choices"]) > 0:
            text = result["choices"][0]["text"]
            print(text)
            print("-" * 60)
            print("Usage:", result.get("usage", {}))
        else:
            print(json.dumps(result, indent=2))
        print("-" * 60)
    except Exception as e:
        print(f"✗ Text completion failed: {e}")
        return False
    print()

    print("=" * 60)
    print("✓ All tests passed!")
    print("=" * 60)
    print()
    print("vLLM API is ready to use!")
    print()
    print("OpenAI-compatible endpoints:")
    print(f"  - Chat: POST {api_url}/chat/completions")
    print(f"  - Completions: POST {api_url}/completions")
    print(f"  - Models: GET {api_url}/models")
    print()
    print("Interactive docs at:")
    print(f"  {base_url}/docs")
    print()

    return True


def main():
    """Main function."""
    if len(sys.argv) < 2:
        print("Usage: python test_vllm_client.py <server_ip> [port]")
        print("Example: python test_vllm_client.py 192.168.1.100 8000")
        sys.exit(1)

    server_ip = sys.argv[1]
    port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000

    try:
        success = test_vllm_api(server_ip, port)
        sys.exit(0 if success else 1)
    except KeyboardInterrupt:
        print("\nTest interrupted by user")
        sys.exit(1)


if __name__ == "__main__":
    main()