JNU-TSB

JNU-TSB

JNU-TSB는 한국어 뉴스와 주가 시계열을 함께 다루기 위한 교육용 Time-LLM-style time-series bridge/router입니다.

Repo ID: HONGRIZON/JNU-TSB
Full name: Jeju National University Time-Series Bridge
Nickname: TSB = Time-Series Bridge, also Time-Series Seungbin
Time-series model: amazon/chronos-2
Korean language model: EleutherAI/polyglot-ko-1.3b
Router: stock only, news only, news + stock hybrid

이 저장소는 Chronos-2 또는 Polyglot-Ko의 가중치를 재배포하지 않습니다. 여기에는 가벼운 wrapper 코드, 설정 파일, 예제 코드, 샘플 데이터만 포함되어 있습니다. 두 base model은 실행 시 Hugging Face에서 다운로드됩니다.

개요

JNU-TSB는 한국어 금융 뉴스 제목을 일별 공변량으로 변환하고, 이를 Chronos-2에 전달해 공변량 기반 시계열 예측을 수행하는 wrapper-style model repo입니다.

뉴스 제목
  -> Polyglot-Ko / keyword fallback
  -> 일별 14차원 이벤트 공변량
  -> Chronos-2 covariate-informed forecasting

주가 시계열
  -> Chronos-2 forecasting

이 구조는 Time-LLM-style입니다. 원 논문의 Time-LLM reprogramming architecture를 엄밀히 재구현한 것은 아닙니다. 숫자 시계열 예측은 Chronos-2가 담당하고, 한국어 LLM은 뉴스 텍스트를 구조화된 공변량으로 바꾸는 역할을 맡습니다.

라우터 구조

JNU-TSB는 입력에 따라 세 가지 경로 중 하나를 자동 선택합니다.

하이브리드 경로는 다음 순서로 동작합니다.

한국어 뉴스
  -> 이벤트/감성 추출
  -> 일별 14차원 covariate 생성
  -> 주가 context dataframe과 merge
  -> Chronos-2 predict_df 호출
  -> forecast 반환

14차원 뉴스 공변량

뉴스는 하루 단위로 집계되어 아래 14개 공변량으로 변환됩니다.

설치

pip install -U transformers torch accelerate pandas pyarrow chronos-forecasting

R에서 사용할 경우 reticulate 가상환경에 위 Python 패키지를 설치하면 됩니다.

Python 빠른 시작

빠른 테스트에서는 use_llm_extractor=False를 사용할 수 있습니다. 이 경우 Polyglot-Ko를 로드하지 않고 keyword fallback만 사용하므로 가볍게 실행됩니다.

from transformers import pipeline

pipe = pipeline(
    task="jnu-tsb",
    model="HONGRIZON/JNU-TSB",
    trust_remote_code=True,
    device=-1,  # CPU. GPU 0번을 쓰려면 0으로 변경
)

stock = [
    {"timestamp": "2024-12-01", "target": 71000},
    {"timestamp": "2024-12-02", "target": 71800},
    {"timestamp": "2024-12-03", "target": 70400},
    {"timestamp": "2024-12-04", "target": 70900},
    {"timestamp": "2024-12-05", "target": 72100},
]

news = [
    {"date": "2024-12-01", "title": "삼성전자 HBM 신제품 출시"},
    {"date": "2024-12-02", "title": "반도체 업황 둔화 우려"},
]

result = pipe(
    {"stock": stock, "news": news},
    prediction_length=3,
    use_llm_extractor=False,
)

print(result)

AutoModel 직접 사용

from transformers import AutoModel

model = AutoModel.from_pretrained(
    "HONGRIZON/JNU-TSB",
    trust_remote_code=True,
)

result = model.predict(
    stock=[{"timestamp": "2024-12-01", "target": 71000}],
    news=[{"date": "2024-12-01", "title": "삼성전자 HBM 신제품 출시"}],
    prediction_length=3,
    use_llm_extractor=False,
)

print(result)

R 빠른 시작

library(reticulate)

# 최초 1회만 실행:
# reticulate::virtualenv_create("jnu-tsb-env")
# reticulate::virtualenv_install(
#   "jnu-tsb-env",
#   c("transformers", "torch", "accelerate", "pandas", "pyarrow", "chronos-forecasting")
# )

use_virtualenv("jnu-tsb-env", required = TRUE)
transformers <- import("transformers")

pipe <- transformers$pipeline(
  task = "jnu-tsb",
  model = "HONGRIZON/JNU-TSB",
  trust_remote_code = TRUE,
  device = -1L
)

stock <- list(
  list(timestamp = "2024-12-01", target = 71000),
  list(timestamp = "2024-12-02", target = 71800),
  list(timestamp = "2024-12-03", target = 70400)
)

news <- list(
  list(date = "2024-12-01", title = "삼성전자 HBM 신제품 출시"),
  list(date = "2024-12-02", title = "반도체 업황 둔화 우려")
)

result <- pipe(
  list(stock = stock, news = news),
  prediction_length = 3L,
  use_llm_extractor = FALSE
)

print(py_to_r(result))

입력 형식

stock

stock은 pandas DataFrame, list of dicts, 또는 dict of columns 형식으로 넣을 수 있습니다. 최소 컬럼은 다음 두 개입니다.

timestamp: 날짜 또는 시간
target: 예측 대상 값, 예: 종가

item_id가 없으면 내부적으로 series_0이 자동 부여됩니다.

news

news는 list of dicts 형식입니다. 각 항목은 최소한 날짜와 제목을 가져야 합니다.

[
  {"date": "2024-12-01", "title": "삼성전자 HBM 신제품 출시"},
  {"date": "2024-12-02", "title": "반도체 업황 둔화 우려"}
]

title 대신 headline, text, content도 인식합니다.

future_news와 future_covariates

미래에 이미 알려진 뉴스나 일정이 있을 때만 future_news 또는 future_covariates를 사용하세요. 일반 뉴스 데이터는 보통 미래 값을 알 수 없으므로, 과거 뉴스는 context 구간의 past covariate로만 쓰는 것이 안전합니다.

출력 예시

출력은 사용된 route와 예측 결과를 함께 반환합니다.

route: text_only | chronos_only | hybrid
repo_id: HONGRIZON/JNU-TSB
forecast: 예측 결과 또는 이벤트/공변량 결과
used_naive_fallback: Chronos-2 실행 실패 시 fallback 사용 여부

중요한 주의사항

• 이 모델은 교육/연구 데모용입니다. 투자 조언이나 실제 매매 판단에 사용하지 마세요.
• EleutherAI/polyglot-ko-1.3b는 instruction-tuned JSON extractor가 아니라 base language model입니다. 따라서 JSON 추출이 실패할 수 있고, 이 저장소는 keyword fallback을 함께 제공합니다.
• Chronos-2 또는 Polyglot-Ko 가중치를 이 저장소에 포함하지 않습니다. 실행 시 각 upstream repo에서 다운로드합니다.
• 이 저장소는 원 논문 Time-LLM을 그대로 재구현한 것이 아니라, 한국어 뉴스와 시계열 예측을 연결하는 Time-LLM-style wrapper/router입니다.

라이선스

Wrapper 코드는 Apache-2.0으로 배포됩니다. Upstream base model인 amazon/chronos-2와 EleutherAI/polyglot-ko-1.3b는 각 Hugging Face repo의 라이선스와 사용 조건을 따릅니다.