AI 함수

AI 함수는 ClickHouse에 내장된 함수로, AI를 호출하거나 임베딩을 생성해 데이터를 처리하고, 정보를 추출하거나, 데이터를 분류하는 등의 작업에 사용할 수 있습니다...

참고

AI 함수는 예측하기 어려운 출력을 반환할 수 있습니다. 결과는 프롬프트의 품질과 사용된 모델에 크게 좌우됩니다.

모든 함수는 다음을 제공하는 공통 인프라를 사용합니다:

• 할당량 적용: 토큰에 대한 쿼리별 제한(ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query)과 API 호출에 대한 쿼리별 제한(ai_function_max_api_calls_per_query).
• 백오프를 사용한 재시도: 일시적인 실패는 재시도되며(ai_function_max_retries), 이때 지수 백오프가 적용됩니다(ai_function_retry_initial_delay_ms).

설정

AI 함수는 프로바이더 자격 증명과 설정을 저장하는 명명된 컬렉션(named collection) 을 참조합니다. 각 함수의 첫 번째 인수는 이 컬렉션의 이름입니다.

프로바이더 자격 증명이 포함된 명명된 컬렉션을 생성하는 예시 문:

CREATE NAMED COLLECTION ai_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';

명명된 컬렉션 매개변수

매개변수	Type	Default	설명
provider	String	—	모델 프로바이더입니다. 지원값: 'openai', 'anthropic'입니다. 아래 참고를 확인하십시오.
endpoint	String	—	API 엔드포인트 URL입니다.
model	String	—	모델 이름입니다(예: 'gpt-4o-mini', 'text-embedding-3-small').
api_key	String	—	프로바이더 인증 키입니다.
max_tokens	UInt64	1024	API 호출당 출력 토큰의 최대 개수입니다.
api_version	String	—	API 버전 문자열입니다. Anthropic에서 사용합니다('2023-06-01').

참고

provider = 'openai'로 설정하고 endpoint가 서비스을 가리키도록 지정하면 OpenAI 호환 API(예: vLLM, Ollama, LiteLLM)를 사용할 수 있습니다.

쿼리 수준 설정

모든 AI 관련 설정은 설정 문서의 ai_function_ 접두사 항목 아래에 나열되어 있습니다.

지원되는 프로바이더

프로바이더	provider 값	채팅 기능	비고
OpenAI	'openai'	예	기본 프로바이더입니다.
Anthropic	'anthropic'	예	/v1/messages 엔드포인트를 사용합니다.

관측성

AI 함수 활동은 ClickHouse ProfileEvents를 통해 추적할 수 있습니다:

ProfileEvent	Description
AIAPICalls	AI 프로바이더로 전송된 HTTP 요청 수입니다.
AIInputTokens	소비된 총 입력 토큰 수입니다.
AIOutputTokens	소비된 총 출력 토큰 수입니다.
AIRowsProcessed	결과를 반환한 행 수입니다.
AIRowsSkipped	건너뛴 행 수입니다(QUOTA를 초과했거나 ai_function_throw_on_error = 0에서 오류가 발생한 경우).

다음과 같이 이러한 이벤트를 쿼리하십시오:

SELECT
    ProfileEvents['AIAPICalls'] AS api_calls,
    ProfileEvents['AIInputTokens'] AS input_tokens,
    ProfileEvents['AIOutputTokens'] AS output_tokens
FROM system.query_log
WHERE query_id = 'query_id'
AND type = 'QueryFinish'
ORDER BY event_time DESC;