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	—	프로바이더 인증 키입니다. 선택 사항입니다. 생략하면 인증 header가 전송되지 않으므로 인증이 필요하지 않은 OpenAI 호환 서버를 대상으로 지정할 수 있습니다.
max_tokens	UInt64	1024	API 호출당 출력 토큰의 최대 개수입니다.
api_version	String	—	API 버전 문자열입니다. Anthropic에서 사용합니다('2023-06-01').

참고

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

쿼리 수준 설정

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

엔드포인트 호스트 제한

AI 명명된 컬렉션의 endpoint URL은 서버가 자체 신원으로 연결하는 아웃바운드 대상이며, 지정된 경우 요청 헤더에 해당 명명된 컬렉션의 api_key를 담아 전송할 수 있습니다. 기본적으로 ClickHouse는 모든 호스트를 허용합니다. 함수를 특정 프로바이더 집합으로 제한하려면 서버 설정에서 remote_url_allow_hosts를 구성하십시오. 예:

<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>

이 설정은 서버 전체에 적용되며, HTTP를 사용하는 모든 기능에 영향을 줍니다.

지원되는 프로바이더

프로바이더	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;

aiClassify

도입 버전: v26.4.0

주어진 텍스트를 LLM 프로바이더를 사용해 제공된 카테고리 중 하나로 분류합니다.

이 함수는 텍스트를 고정된 분류 프롬프트 및 JSON schema 응답 형식과 함께 전송하며, 모델이 제공된 레이블 중 정확히 하나만 반환하도록 제한합니다. 응답이 {"category": "..."} 형태의 JSON 객체로 반환되면 해당 레이블을 추출하여 레이블 문자열을 반환합니다.

첫 번째 인수는 프로바이더, 모델, 엔드포인트, 그리고 선택적으로 API key를 지정하는 명명된 컬렉션입니다.

구문

aiClassify(collection, text, categories[, temperature])

별칭: AIClassify

인수

• collection — 프로바이더 자격 증명과 구성이 포함된 명명된 컬렉션의 이름입니다. String
• text — 분류할 텍스트입니다. String
• categories — 후보 범주 레이블의 상수 목록입니다. Array(String)
• temperature — 무작위성 수준을 제어하는 샘플링 온도입니다. 기본값: 0.0. Float64

반환값

제공된 범주 레이블 중 하나를 반환합니다. 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. String

예시

감정 분류

SELECT aiClassify('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral'])

positive

컬럼 분류하기

SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5

aiEmbed

도입 버전: v26.6.0

구성된 AI 프로바이더를 사용하여 지정된 텍스트의 임베딩 벡터를 생성합니다.

이 함수는 텍스트를 구성된 임베딩 엔드포인트로 전송하고, 결과 벡터를 Array(Float32)로 반환합니다. 호출당 오버헤드를 줄이기 위해 단일 행 블록 내에서는 입력이 HTTP 요청당 최대 ai_function_embedding_max_batch_size 개까지 배치로 묶여 처리됩니다.

첫 번째 인수는 제공자, 모델, 엔드포인트, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션입니다. 선택적 dimensions 인수는 모델이 이를 지원하는 경우(예: OpenAI's text-embedding-3-*) 지정한 크기의 벡터를 요청하며, 그렇지 않으면 모델의 네이티브 크기가 반환됩니다.

구문

aiEmbed(collection, text[, dimensions])

인수

• collection — 프로바이더 자격 증명과 구성이 포함된 명명된 컬렉션의 이름입니다. String
• text — 임베딩할 텍스트입니다. String
• dimensions — 출력 벡터의 선택적 목표 차원 수입니다. 0이거나 생략하면 모델의 네이티브 크기를 의미합니다. UInt64

반환 값

임베딩 벡터 또는 입력이 NULL이거나 비어 있거나, 요청이 실패했지만 ai_function_throw_on_error가 비활성화되어 있거나, ai_function_throw_on_quota_exceeded가 비활성화된 상태에서 QUOTA를 초과한 경우 빈 배열을 반환합니다. Array(Float32)

예시

단일 문자열 임베딩

SELECT aiEmbed('ai_credentials', 'Hello world')

차원을 명시적으로 지정

SELECT aiEmbed('ai_credentials', 'Hello world', 256)

텍스트 컬럼 임베딩하기

SELECT aiEmbed('ai_credentials', title, 256) FROM articles LIMIT 10

aiExtract

도입 버전: v26.4.0

LLM 프로바이더를 사용해 비정형 텍스트에서 구조화된 정보를 추출합니다.

세 번째 인수는 자유 형식의 자연어 지시문(예: 'the main complaint')이거나 '{"field_a": "description of field a", "field_b": "description of field b"}' 형식의 JSON으로 인코딩된 schema일 수 있습니다.

지시문 모드에서 함수는 추출된 값을 일반 문자열로 반환하며, 아무것도 찾지 못한 경우 빈 문자열을 반환합니다. schema 모드에서 함수는 요청된 schema와 키가 일치하는 JSON 객체 문자열을 반환하며, 누락된 필드는 null입니다.

첫 번째 인수는 프로바이더, 모델, 엔드포인트와 선택적으로 API key를 지정하는 명명된 컬렉션입니다.

구문

aiExtract(collection, text, instruction_or_schema[, temperature])

별칭: AIExtract

인수

• collection — 프로바이더 자격 증명과 구성이 포함된 명명된 컬렉션의 이름입니다. String
• text — 정보를 추출할 텍스트입니다. String
• instruction_or_schema — 자유 형식의 추출 지침 또는 추출할 필드를 설명하는 상수 JSON 객체입니다. const String
• temperature — 무작위성을 제어하는 샘플링 온도입니다. 기본값은 0.0입니다. const Float64

반환값

단일 추출 값(지침 모드) 또는 JSON 객체 문자열(schema 모드)입니다. 요청이 실패하고 ai_function_throw_on_error가 비활성화되어 있으면 컬럼 타입의 기본값(빈 문자열)을 반환합니다. String

예시

자유 형식 지침

SELECT aiExtract('ai_credentials', 'The package arrived late and was damaged.', 'the main complaint')

late and damaged package

schema 추출

SELECT aiExtract('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

aiGenerate

도입 버전: v26.4.0

LLM 프로바이더를 사용해 프롬프트로부터 자유 형식 텍스트 콘텐츠를 생성합니다.

이 함수는 구성된 AI 프로바이더에 프롬프트를 전송하고 생성된 텍스트를 반환합니다. 모델의 동작(예: 어조, 형식, 역할)을 유도하기 위해 선택적으로 system prompt를 제공할 수 있습니다. system prompt를 지정하지 않으면 기본 system prompt는 다음과 같습니다: You are a helpful assistant. Provide a clear and concise response.

첫 번째 인수는 프로바이더, 모델, 엔드포인트, 그리고 선택적으로 API key를 지정하는 명명된 컬렉션입니다.

구문

aiGenerate(collection, prompt[, system_prompt[, temperature]])

별칭: AIGenerate

인수

• collection — 프로바이더 자격 증명과 구성이 포함된 명명된 컬렉션의 이름입니다. String
• prompt — 모델에 보낼 사용자 프롬프트 또는 질문입니다. String
• system_prompt — 모델의 동작(예: 페르소나, 출력 형식)을 안내하는 선택적 상수 시스템 수준 지시문이며, 각 프롬프트와 함께 전송됩니다. String
• temperature — 무작위성을 제어하는 샘플링 온도입니다. 기본값은 0.7입니다. Float64

반환값

생성된 텍스트 응답 또는 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우 컬럼 타입의 기본값(빈 문자열)입니다. String

예시

간단한 질문

SELECT aiGenerate('ai_credentials', 'What is 2 + 2? Reply with just the number.')

4

시스템 프롬프트 사용 시

SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')

컬럼 값 요약하기

SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

aiTranslate

도입 버전: v26.4.0

LLM 프로바이더를 사용하여 지정된 대상 언어로 주어진 텍스트를 번역합니다.

추가 스타일 또는 방언 지침은 네 번째 인수로 전달할 수 있습니다(예: '기술 용어는 번역하지 않음').

첫 번째 인수는 프로바이더, 모델, 엔드포인트, 그리고 선택적으로 API key를 지정하는 명명된 컬렉션입니다.

구문

aiTranslate(collection, text, target_language[, instructions[, temperature]])

별칭: AITranslate

인수

• collection — 프로바이더 자격 증명과 구성이 포함된 명명된 컬렉션의 이름입니다. String
• text — 번역할 텍스트입니다. String
• target_language — 대상 언어 이름 또는 BCP-47 코드입니다(예: 'French', 'es-MX'). String
• instructions — 번역기에 전달할 선택적 상수 추가 지침입니다. String
• temperature — 무작위성을 제어하는 샘플링 온도입니다. 기본값: 0.3. Float64

반환값

번역된 텍스트 또는 요청이 실패했고 ai_function_throw_on_error가 비활성화된 경우 컬럼 타입의 기본값(빈 문자열)입니다. String

예시

프랑스어로 번역

SELECT aiTranslate('ai_credentials', 'Hello, world!', 'French')

Bonjour le monde!

스타일 지침에 따라 일본어로 번역

SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5