뉴스 LLM 프록시 — Azure Functions 셋업 기록

날짜 2026-07-27 · 작업 대상 kospi-avenger 게임의 뉴스 시스템 백엔드

1. 왜 중계 서버가 필요한가

게임 클라(Godot Android)에서 Azure OpenAI 를 직접 호출하면 안 되는 3가지 이유:

1. API 키 유출 = 결제 폭탄. APK 디컴파일로 키 추출 → 제3자가 무제한 사용. Azure OpenAI 는 요청당 과금이라 크레딧 소진 위험.
2. 프롬프트 튜닝 사이클. "미친 무빙" 로직·프롬프트를 서버에 두면 앱 재배포 없이 실시간 튜닝. 클라에 두면 APK 새로 올려야 함.
3. Rate limit·캐싱 제어. 유저별 quota, 유사 시장 상태 응답 재사용 → 비용 절감. 서버 없이는 통제 불가.

2. 최종 아키텍처

3. 생성된 Azure 리소스 (전부 신규, 프로덕션 격리)

모델 선택 히스토리

처음에 gpt-4o-mini 를 시도했으나 "deprecating state" 로 신규 배포 불가. gpt-4.1-nano 역시 동일. 최신 세대인 gpt-5-nano 로 확정.

4. 사용된 명령어 순서 (재현 가능)

4-1. 사전 확인

az --version           # 2.60+
node --version         # v20+
npm --version
az account show        # 현재 subscription
az cognitiveservices account list  # 기존 OpenAI 리소스 파악

4-2. Azure Functions Core Tools 설치

npm install -g azure-functions-core-tools@4 --unsafe-perm true
func --version         # 4.12+

4-3. Azure 리소스 생성

# Resource Group
az group create --name kospi-avenger-rg --location koreacentral

# Azure OpenAI 계정
az cognitiveservices account create \
  --name kospi-avenger-aoai \
  --resource-group kospi-avenger-rg \
  --location koreacentral \
  --kind OpenAI \
  --sku S0 \
  --yes

# 모델 배포 (gpt-5-nano)
az cognitiveservices account deployment create \
  --name kospi-avenger-aoai \
  --resource-group kospi-avenger-rg \
  --deployment-name gpt-5-nano \
  --model-name gpt-5-nano \
  --model-version "2025-08-07" \
  --model-format OpenAI \
  --sku-capacity 30 \
  --sku-name GlobalStandard

# Storage Account (Function App 필수 종속)
az storage account create \
  --name kospiavengerstore \
  --resource-group kospi-avenger-rg \
  --location koreacentral \
  --sku Standard_LRS \
  --kind StorageV2

# Function App — Windows Consumption 필수 (Linux + Node v4 조합 SCM 죽음 이슈)
az functionapp create \
  --name kospi-news-fn \
  --resource-group kospi-avenger-rg \
  --consumption-plan-location koreacentral \
  --runtime node \
  --runtime-version 24 \
  --functions-version 4 \
  --storage-account kospiavengerstore
  # ← --os-type 명시하지 않으면 Windows (Windows 사용 권장)

4-4. 프록시 프로젝트 스캐폴드 (로컬)

mkdir kospi_news_proxy && cd kospi_news_proxy
func init . --worker-runtime node --language typescript --model V4
func new --template "HTTP trigger" --name generateNews --authlevel function
npm install openai zod
git init

4-5. local.settings.json 작성 (개발용, 커밋 X)

KEY=$(az cognitiveservices account keys list \
  --name kospi-avenger-aoai --resource-group kospi-avenger-rg \
  --query "key1" -o tsv)
ENDPOINT=$(az cognitiveservices account show \
  --name kospi-avenger-aoai --resource-group kospi-avenger-rg \
  --query "properties.endpoint" -o tsv)

cat > local.settings.json <<EOF
{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "AZURE_OPENAI_ENDPOINT": "${ENDPOINT}",
    "AZURE_OPENAI_KEY": "${KEY}",
    "AZURE_OPENAI_DEPLOYMENT": "gpt-5-nano",
    "AZURE_OPENAI_API_VERSION": "2025-01-01-preview",
    "GAME_SHARED_SECRET": "<32바이트 랜덤 base64>"
  },
  "Host": { "CORS": "*" }
}
EOF

4-6. Shared Secret 생성

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

4-7. 로컬 빌드 + 실행

npm run build
func start
# → Functions: generateNews: [POST] http://localhost:7071/api/generateNews

4-8. Azure App Settings 등록 + 코드 배포

# App Settings (환경 변수) — 다시 stdout 노출 없이
KEY=$(az cognitiveservices account keys list --name kospi-avenger-aoai --resource-group kospi-avenger-rg --query "key1" -o tsv)
ENDPOINT=$(az cognitiveservices account show --name kospi-avenger-aoai --resource-group kospi-avenger-rg --query "properties.endpoint" -o tsv)

az functionapp config appsettings set \
  --name kospi-news-fn --resource-group kospi-avenger-rg \
  --settings \
    AZURE_OPENAI_ENDPOINT="$ENDPOINT" \
    AZURE_OPENAI_KEY="$KEY" \
    AZURE_OPENAI_DEPLOYMENT="gpt-5-nano" \
    AZURE_OPENAI_API_VERSION="2025-01-01-preview" \
    GAME_SHARED_SECRET="<프로덕션 새 시크릿>" \
  -o none

# 코드 배포
cd kospi_news_proxy
func azure functionapp publish kospi-news-fn --typescript

# Function key 조회 (배포 후 1-3분 대기 필요)
az functionapp function keys list \
  --resource-group kospi-avenger-rg \
  --name kospi-news-fn \
  --function-name generateNews \
  --query "default" -o tsv

5. 프록시 프로젝트 구조

kospi_news_proxy/
├── .gitignore                       # local.settings.json 자동 포함
├── package.json                     # openai, zod deps
├── tsconfig.json
├── host.json                        # Functions v4 런타임 설정
├── local.settings.json              # 로컬 env vars (커밋 X)
├── src/
│   └── functions/
│       └── generateNews.ts          # 유일한 함수 — HTTP POST 트리거
└── dist/                            # TypeScript 빌드 산출물 (커밋 X)

generateNews.ts 요약

• 인증: X-Game-Auth 헤더가 GAME_SHARED_SECRET 과 일치해야 통과. 아니면 401.
• 요청 스키마 (Zod): { holdings, cash, realized_pnl, week, weekday, ticker_meta, count }. 스키마 불일치 시 400.
• 프롬프트: "코스피 특유의 어처구니없는 연관성 활용 — 이름 겹침·테마 편승·CEO 동명이인 등" 명시. 최상위 { "items": [...] } 강제.
• LLM 호출: reasoning_effort: minimal, max_completion_tokens: 4000, response_format: json_object.
• 응답 검증 (Zod): items[] 각 원소가 {kind, headline, body, impacts[]}. impacts.code 를 요청된 ticker_meta 안 종목으로만 필터.

6. 로컬 실행 방법

1. cd kospi_news_proxy
2. npm run build
3. func start (백그라운드 실행 시 func start &)
4. 테스트:

   curl -X POST http://localhost:7071/api/generateNews \
     -H "X-Game-Auth: <GAME_SHARED_SECRET>" \
     -H "Content-Type: application/json" \
     --data @sample_req.json

5. 응답:

   {
     "items": [
       {
         "kind": "rumor",
         "headline": "조선양조간장, AI 발언 인연으로 급등 여부 주목",
         "body": "시장에 떠도는 루머성 소문이 확산되며...",
         "impacts": [
           { "code": "108860", "fair_value_delta_pct": 1.8,
             "reason": "이름 겹침 효과로 인한 단기 매수세 유입" }
         ]
       },
       ...
     ],
     "usage": { "prompt_tokens": 774, "completion_tokens": 486 }
   }

7. Azure 배포 방법

1. App Settings 등록 완료 (§4-8 참조).
2. 코드 배포: func azure functionapp publish kospi-news-fn --typescript
3. 초기화 대기 (Consumption plan 첫 배포 시 1-3분). 이 기간에 func list · keys list 명령이 400 리턴하는 건 정상.
4. Function key 조회:

   az functionapp function keys list \
     --resource-group kospi-avenger-rg \
     --name kospi-news-fn \
     --function-name generateNews \
     --query "default" -o tsv

5. 원격 엔드포인트:

   https://kospi-news-fn.azurewebsites.net/api/generateNews?code=<function-key>

8. 알려진 quirk 와 대처

9. Godot 클라이언트 연동 (완료)

2026-07-27 완료. 게임에서 실제로 kospi-news-fn 을 호출해 뉴스를 받아 시장에 반영하고 UI 에 표시하는 3피스가 배선되었다.

9-1. 파일 인벤토리

9-2. .news-key 셋업 (사용자 로컬)

# .news-key.example 을 복사한 뒤 값 채워넣기
cp .news-key.example .news-key

# .news-key 형식:
{
  "endpoint": "https://kospi-news-fn.azurewebsites.net/api/generateNews",
  "function_key": "<az functionapp function keys list ... 조회>",
  "shared_secret": "<App Setting GAME_SHARED_SECRET 과 동일>"
}

# function key 조회
az functionapp function keys list --name kospi-news-fn --resource-group kospi-avenger-rg --function-name generateNews

# shared secret 조회 (App Setting 에 저장된 값)
az functionapp config appsettings list --name kospi-news-fn --resource-group kospi-avenger-rg --query "[?name=='GAME_SHARED_SECRET'].value" -o tsv

9-3. 트리거 정책

• 자동: NewsClient._on_tick(sim_delta) 가 sim_delta 를 누산해 REQUEST_EVERY_SIM_SECONDS=3600 (게임 내 1시간) 마다 request_news() 호출. 게임 하루 = 23400 sim sec 이므로 하루 6-7 배치, 배치당 3-5 뉴스 = 하루 20+ 이벤트 (SIM_SPEC 3-5개/일 기준 상회).
• 수동: Services.news_client.request_news(4) 직접 호출 가능 (디버그·강제 fetch).
• 중복 방지: _inflight 플래그로 응답 대기 중엔 신규 요청 무시.
• 타임아웃: 30초 (gpt-5-nano cold start 최대 15초 + 여유).

9-4. 요청 / 응답 스키마

// 요청 (게임 → Azure Function)
{
  "holdings": { "005930": { "qty": 10, "avg_price": 70000 } },
  "cash": 9300000,
  "realized_pnl": 0,
  "week": 1,
  "weekday": 0,
  "ticker_meta": {
    "005930": {"display_name": "한성전자", "sector": "반도체/IT", "archetype": "large_cap", "reference_price": 70000},
    ... 20 종목
  },
  "count": 4
}

// 응답 (Azure Function → 게임)
{
  "items": [
    { "kind": "rumor" | "disclosure" | "macro" | "sector",
      "headline": "한줄 헤드라인",
      "body": "본문 요약",
      "impacts": [{"code": "005930", "fair_value_delta_pct": 3.5, "reason": "..."}] }
  ]
}

9-5. 시장 반영 로직

• 각 impact 마다 Ticker.fair_value *= (1 + delta_pct/100).
• 찌라시는 진위 미확정 → LLM 델타의 40% 만 반영 (기존 정적 deck 정책 유지).
• price_cap_hi/lo 로 clamp (상한가/하한가 ±30% 준수).
• 가격은 직접 건드리지 않음. fair_value 변화 → Fundamentalist 봇이 매수/매도 → Momentum 봇이 추격 → 실제 가격 이동. SIM_SPEC §4.3 인과 사슬 유지.

9-6. 운영 체크리스트

• Azure Cost Alert 설정 (kospi-avenger-rg 월 $10 등).
• App Insights 대시보드로 응답 지연·에러율 모니터링.
• 프롬프트 튜닝 사이클: generateNews.ts 수정 → func azure functionapp publish.
• Function key 롤링: az functionapp function keys set 로 정기 교체 (분기 1회). 롤링 후 .news-key 값도 갱신.

이 문서는 docs/NEWS_LLM_SETUP.html 에 저장. 프록시 저장소는 게임 리포와 분리 (C:\files\Dev\13.Godot\kospi_news_proxy).