Skip to main content
xgboost (XGBOOST) 딕셔너리는 로드 시점에 학습용 행이 담긴 원본 테이블을 사용해 XGBoost 그래디언트 부스팅 모델을 학습한 다음, 입력된 피처 벡터에 대해 숫자형 대상 값을 예측합니다. 피처 컬럼이 딕셔너리 키가 되며, 단일 속성은 모델이 학습하는 대상 값입니다. 이 딕셔너리는 피처가 숫자형인 표 형식 데이터의 회귀 및 이진 분류에 적합합니다. 예를 들어 여러 측정값으로 특정 값을 예측하거나, 학습된 대상 값을 기준으로 행에 점수를 매기는 작업에 활용할 수 있습니다. 다중 클래스 목적 함수는 지원되지 않습니다(레이아웃 매개변수 참고).
XGBoost 통합은 실험적 기능입니다. XGBOOST 딕셔너리를 생성하거나 predictXGBoost를 호출하기 전에 enable_xgboost 설정으로 활성화하십시오.
CREATE DICTIONARY만 지원됩니다. 서버 설정 파일에 정의된 XGBOOST 딕셔너리는 로드되지 않습니다.
이 딕셔너리는 predictXGBoost로만 쿼리할 수 있습니다. 이 함수는 피처를 개별 인수로 받아 예측값을 반환하며, 추가 예측 매개변수도 지정할 수 있습니다. 이 딕셔너리는 행이 아닌 학습된 모델을 저장하므로 dictGet, dictHas, SELECT * FROM dict와 같은 일반 딕셔너리 인터페이스는 지원되지 않으며, 사용 시 오류가 발생합니다.

빠른 시작

여기서는 선형 대상 y = 2*x1 + 3*x2를 대상으로 회귀 모델을 학습시킵니다. 1. 원본 테이블을 생성합니다. 이 테이블에는 학습용 행이 저장되며, 피처(feature) 컬럼 다음에 대상 컬럼이 오도록 구성합니다.
2. 학습 데이터 삽입:
3. XGBOOST 레이아웃(layout)으로 딕셔너리를 생성합니다. 피처(feature) 컬럼은 키가 되고, y는 대상 속성이 됩니다:
PRIMARY KEY (x1, x2)는 x1과 x2를 피처로 지정합니다. 모델이 학습하는 대상은 y이며, 키에 포함되지 않은 유일한 컬럼이므로 자동으로 추론됩니다. LAYOUT의 매개변수는 XGBoost 하이퍼파라미터입니다(레이아웃 매개변수 참조). 4. 예측 — predictXGBoost는 피처를 위치 기반으로 전달받아 예측값을 반환합니다.
실제 값(ground truth)은 2*1 + 3*2 = 8이므로 모델의 예측값은 8에 가깝습니다.

동작 방식

학습(로드 시점). 각 소스 행은 (features..., target) 형태의 관측값입니다. 딕셔너리가 로드되면 소스를 블록 단위로 읽은 뒤, 전체 데이터에 대해 모델을 한 번 학습합니다. 피처 값과 대상 값은 부동 소수점 수로 읽히므로 키 열(Key Columns)은 숫자형이어야 하고, 대상 속성은 floating-point 타입이어야 합니다(딕셔너리 구조 참조).
학습 시 전체 학습 세트를 메모리에 보관합니다. 소스를 블록 단위로 읽는다고 해서 외부 메모리(out-of-core) 학습이 되는 것은 아닙니다. 각 블록은 소비되지 않고 누적되므로, 첫 번째 부스팅 라운드가 시작되기 전에 전체 학습 세트가 메모리에 올라가며 마지막 라운드가 끝날 때까지 메모리에 유지됩니다.
예측(쿼리 시점). 예측 시 모델은 키 열(Key Columns)이 선언된 순서대로 구성된 피처 벡터를 입력받아 학습된 부스터에 통과시킨 후 Float64 값을 반환합니다. NULL 피처는 결측값으로 모델에 전달되며, XGBoost는 학습 과정에서 익힌 방식대로 이를 처리하므로 예측 결과가 NULL이 되는 경우는 없습니다. 모든 피처가 상수이면 모델은 행마다 평가되지 않고 블록당 한 번만 평가됩니다. 모델은 영구 저장되지 않습니다. 모델은 딕셔너리가 로드되어 있는 동안에만 메모리에 존재하며, 서버 재시작 후를 포함해 로드될 때마다 소스로부터 다시 학습됩니다. 모델 재학습. 로드할 때마다 처음부터 새로 학습하므로, SYSTEM RELOAD DICTIONARY를 실행하면 원본 테이블의 현재 내용을 기준으로 모델이 재학습됩니다.
LIFETIME을 0이 아닌 값으로 설정해도 재학습이 수행됩니다. 수명(lifetime)에 따라 트리거되어 다시 로드하는 것도 일반 로드와 다르지 않기 때문입니다. 학습 데이터가 늘어날 때 모델을 주기적으로 갱신하려면 이 설정을 사용하십시오.

딕셔너리 구조

XGBOOST 딕셔너리는 다음과 같이 고정된 구조적 형태(Shape)를 가집니다.
  • PRIMARY KEY는 네이티브 숫자 유형(정수(integer) 및 부동 소수점 수)의 컬럼 하나 이상으로 구성되며, 이 컬럼들이 피처가 됩니다. 쿼리 시점에 이 “키”는 저장된 조회(lookup) 키가 아니라 예측에 사용할 피처 벡터입니다. 피처 순서는 키 컬럼의 선언 순서를 따르며, predictXGBoost는 위치 인수를 이 순서대로 바인딩합니다.
  • 이와 함께 Float32 또는 Float64 타입의 속성을 정확히 1개 선언하십시오. 이 속성은 모델이 학습하는 대상입니다. 이 속성은 항상 피처 키에 속하지 않는 유일한 컬럼으로 추론되므로 이름을 지정하는 매개변수는 따로 없으며, 속성을 2개 이상 선언하면 오류가 발생합니다.
이러한 요구 사항을 충족하지 않는 컬럼은 딕셔너리를 생성할 때가 아니라 로드할 때 거부됩니다.

레이아웃(layout) 매개변수

아래에 나열된 매개변수만 허용되며, 그 외의 이름을 사용하면 로드가 실패합니다. 따라서 오타가 있으면 조용히 무시되지 않고 모델 학습 시점에 감지됩니다. num_iterations는 ClickHouse가 직접 처리하며(해당 설명 참고), 나머지 매개변수는 모두 문자열 형태 그대로 XGBoost 부스터에 전달되고 XGBoost 자체의 기본값과 값 범위를 따릅니다. 자세한 내용은 XGBoost 매개변수 참고 문서를 참고하십시오. 매개변수 이름은 대소문자를 구분하지 않으며, 각 매개변수는 한 번만 지정할 수 있습니다. 값은 양의 정수, 부동소수점 수 또는 따옴표로 묶은 문자열이어야 합니다. 음수 리터럴은 레이아웃에 전달되기 전에 딕셔너리 DDL 단계에서 거부되므로 seed에 음수를 지정할 수 없습니다. 예를 들어, 스텝 크기 eta도 함께 설정하는 딕셔너리는 다음과 같습니다.

예측 매개변수

predictXGBoost는 피처 뒤에 오는 마지막 인수로, XGBoost 예측 매개변수를 담은 상수 Map을 선택적으로 받을 수 있습니다. 이 Map은 map으로 생성합니다.
매개변수 이름은 XGBoost XGBoosterPredictFromDMatrix의 예측 매개변수에 대응합니다. 아래 키만 허용되며, 그 외의 키를 사용하면 쿼리가 실패합니다. 모든 매개변수는 정수(integer) 또는 불리언이므로 Map 값은 정수 타입이어야 합니다.

참고 사항

  • 계산형 딕셔너리의 의미 체계. 이 딕셔너리는 계산형 딕셔너리입니다. 행 대신 학습된 모델을 보유하며, predictXGBoost로만 쿼리할 수 있습니다. 일반 딕셔너리 인터페이스는 지원되지 않으며 사용 시 오류가 발생합니다. 해당 작업은 dictGet(조회할 저장된 속성이 없으며, “키”는 예측에 사용할 피처 벡터입니다), dictHas(저장된 키가 없습니다), SELECT * FROM dict, 그리고 딕셔너리를 테이블처럼 조인하는 작업입니다. predictXGBoost가 유일한 진입점이므로, 모든 예측에서 enable_xgboost 설정이 활성화되어 있어야 합니다.
  • 숫자 컬럼만 지원. 모든 피처(키) 컬럼은 네이티브 숫자 유형이어야 하며, 대상 속성은 Float32 또는 Float64여야 합니다. 학습 및 예측 시 값은 부동 소수점으로 읽힙니다. predictXGBoost의 피처 인수는 Nullable일 수도 있습니다. 자세한 내용은 동작 방식을 참조하십시오.
  • system.dictionaries에는 저장된 항목이 표시되지 않습니다. 이 딕셔너리는 행을 저장하지 않고 모델을 학습하므로, direct 딕셔너리와 마찬가지로 element_count는 0이며 bytes_allocated도 0입니다. 학습된 모델은 XGBoost가 관리하며, XGBoost는 사용 중인 메모리 양을 보고하지 않기 때문입니다. query_count와 found_rate는 predictXGBoost가 모델에 전달한 행 수를 집계합니다. 모든 피처가 상수인 호출은 블록당 한 번만 평가되므로, 행마다 집계되지 않고 블록당 1개의 행으로 집계됩니다.
  • 다시 로드하는 데 실패하면 이전 모델이 유지됩니다. 원본 테이블이 삭제되었거나, 스키마가 변경되었거나, 하이퍼파라미터가 더 이상 허용되지 않는 등의 이유로 재학습에 실패하더라도 딕셔너리의 예측이 실패하지는 않습니다. 대신 마지막으로 학습에 성공한 모델을 계속 제공하면서 오류를 기록합니다. 모델이 여전히 현재 소스 데이터를 반영하는지 확인하려면 system.dictionaries에서 last_successful_update_time과 last_exception을 비교하십시오.
  • XGBoost의 메시지는 서버 로그에 기록됩니다. 이 메시지는 XGBoost가 지정한 로그 수준에 따라 XGBoost 로거로 기록되며, 학습 또는 예측을 수행하는 쿼리에 연결되므로 system.text_log에도 표시됩니다. 더 많은 메시지를 보려면 verbosity를 높이십시오.
  • 피처 순서가 중요합니다. predictXGBoost는 위치 기반 피처 인수를 선언 순서대로 키 열(Key Columns)에 바인딩하며, 피처 인수의 개수는 키 열(Key Columns)의 개수와 일치해야 합니다.