AI 함수

AI 함수 (AI Functions)

ClickHouse 내장 함수로 AI를 호출하거나 임베딩을 생성해 데이터를 다루고, 정보를 추출하고, 데이터를 분류하는 등의 작업을 할 수 있어요.

출처: 문서

본문

AI 함수는 ClickHouse에 내장된 함수로, 데이터를 다루기 위해 AI를 호출하거나 임베딩을 생성하고, 정보를 추출하고, 데이터를 분류하는 등의 작업을 할 수 있게 해줘요.

AI 함수는 베타 상태예요. AI 함수는 예측할 수 없는 출력을 반환할 수 있어요. 결과는 프롬프트와 사용된 모델의 품질에 크게 의존해요.

AI 함수는 현재 ClickHouse Cloud 서비스에서는 사용할 수 없어요. 업데이트를 기다려 주세요.

프롬프트 주입(Prompt injection) 입력 텍스트는 모델로 전송되며 모델의 출력을 조종할 수 있어요(프롬프트 주입). 외부·검증되지 않았거나·정화되지 않은 소스의 텍스트에는 모델이 공격자 제어 콘텐츠를 반환하게 하거나, 요청한 형식을 무시하게 하거나, 악성 페이로드를 방출하게 하는 지침이 포함될 수 있어요. AI 함수 출력을 신뢰할 수 없는 것으로 취급하세요: SQL 구성, 셸 명령, 추가 쿼리, 접근 제어 결정 등 다운스트림 단계에서 사용하기 전에 검증하거나 정화하세요.

모든 함수는 공통 인프라를 공유하며 다음을 제공해요:

쿼터 적용(Quota enforcement): 쿼리당 토큰 제한(ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query)과 API 호출 제한(ai_function_max_api_calls_per_query).
백오프 재시도(Retry with backoff): 일시적 실패는 지수 백오프(ai_function_retry_initial_delay_ms)로 재시도돼요(ai_function_max_retries).

구성 (Configuration)

AI 함수는 공급자 자격 증명과 구성을 저장하는 명명된 컬렉션(named collection) 을 참조해요. 함수나 함수 호출마다 다른 명명된 컬렉션을 만들고 사용할 수 있어요. 예를 들어 텍스트 함수(aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact)에는 다른 명명된 컬렉션을, 임베딩 함수(aiEmbed, aiSimilarity)에는 다른 컬렉션을 정의하고 싶을 수 있어요. 두 함수는 다른 엔드포인트가 필요하고 보통 다른 모델을 사용하기 때문이에요. 공급자 자격 증명으로 명명된 컬렉션을 만들고, 하나는 채팅 엔드포인트로, 다른 하나는 임베딩 엔드포인트로 구성하는 예:

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

-- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection,
-- pass it as a positional argument instead. Defining `model` in an embedding collection is an error,
-- not silently ignored.
CREATE NAMED COLLECTION ai_embedding_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/embeddings',
    api_key = 'sk-...';

명명된 컬렉션 매개변수 (Named collection parameters)

매개변수	타입	기본값	설명
`provider`	String	—	모델 공급자. 지원: `'openai'`, `'anthropic'`. 아래 참고 사항 확인.
`endpoint`	String	—	API 엔드포인트 URL.
`model`	String	—	모델 이름(예: `'gpt-4o-mini'`). 텍스트 함수가 사용하며, 임베딩 함수(`aiEmbed`, `aiSimilarity`)는 `model`을 위치 인자로 요구하고 명명된 컬렉션에 `model`이 지정되면 오류를 발생시켜요.
`api_key`	String	—	공급자용 인증 키. 선택 사항: 생략하면 인증 헤더가 전송되지 않아, 인증이 필요 없는 OpenAI 호환 서버를 대상으로 할 수 있어요.
`max_tokens`	UInt64	`1024`	API 호출당 최대 출력 토큰 수.
`api_version`	String	—	API 버전 문자열. Anthropic이 사용해요(`'2023-06-01'`).

provider = 'openai'로 설정하고 endpoint를 서비스로 지정하면 OpenAI 호환 API(vLLM, Ollama, LiteLLM 등)를 사용할 수 있어요.

자격 증명 선택 (Selecting credentials)

함수는 다음 순서로 사용할 명명된 컬렉션을 결정해요:

있으면 매개변수 맵의 credentials 키;
그 외에는 적용 가능한 기본 자격 증명 설정:
- 텍스트 함수(aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact)의 ai_function_text_default_credentials;
- 임베딩 함수(aiEmbed, aiSimilarity)의 ai_function_embedding_default_credentials.

둘 다 설정되지 않으면 호출이 실패해요. 텍스트와 임베딩 함수가 별도의 기본 설정을 사용하는 이유는 채팅 완성 엔드포인트가 임베딩 엔드포인트와 다르기 때문이에요.

SET ai_function_text_default_credentials = 'ai_text_credentials';

-- Uses ai_text_credentials from the setting:
SELECT aiGenerate('What is 2 + 2? Reply with just the number.');

-- Overrides the default for this call:
SELECT aiGenerate('Bonjour', map('credentials', 'other_credentials'));

aiFilter로 자연어 조건을 사용해 행을 필터링할 수 있으며, UInt8을 반환해서 WHERE에서 직접 사용할 수 있어요:

SELECT * FROM reviews
WHERE aiFilter(body, 'the customer is angry about shipping');

매개변수 맵 (Parameter map)

각 함수는 선택적인 Map(String, String)의 끝 매개변수를 받아요. 모든 값은 문자열이에요(숫자는 인용하세요, 예: '0.2'). 알 수 없는 키는 거부돼요. 존재하는 키는 해당 명명된 컬렉션 값을 재정의하고, 없는 키는 명명된 컬렉션(model/max_tokens의 경우) 또는 내장 기본값으로 대체돼요. 예외는 임베딩 함수(aiEmbed, aiSimilarity)로, model을 필수 위치 인자로 받아요(예: aiEmbed(text, model[, params]), aiSimilarity(text1, text2, model[, params])) 매개변수 맵이나 명명된 컬렉션에 설정하면 오류가 발생해요. 이는 재현 가능한 임베딩을 강제하기 위함이에요. 모든 AI 함수에 공통인 매개변수:

키	설명
`credentials`	사용할 명명된 컬렉션(위 참고).
`model`	컬렉션의 `model`을 재정의해요(텍스트 함수만; 임베딩 함수(`aiEmbed`, `aiSimilarity`)는 `model`을 맵 키가 아닌 필수 위치 인자로 받아요).

개별 함수는 함수별 추가 매개변수(max_tokens, temperature, system_prompt, instructions, dimensions 등)를 받아요. 각 함수가 받는 매개변수와 기본값은 아래 함수별 참고를 확인하세요.

SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles;

쿼리 수준 설정 (Query-level settings)

모든 AI 관련 설정은 Settings의 ai_function_ 접두사 아래에 나열돼요.

엔드포인트 호스트 제한 (Restricting endpoint hosts)

AI 명명된 컬렉션의 endpoint URL은 서버가 자신의 정체성으로 연결하는 외부 목적지로, (지정된 경우) 명명된 컬렉션의 api_key를 요청 헤더에 담아 보낼 수 있어요. 기본적으로 ClickHouse는 모든 호스트를 허용해요. 특정 공급자 집합으로 함수를 제한하려면 서버 구성에서 remote_url_allow_hosts를 구성하세요.

전송 보안 (HTTP vs HTTPS)

전송 방식은 endpoint URL의 스킴에 의해서만 결정돼요. 요청 페이로드의 애플리케이션 수준 암호화는 없어요. 전송 중 데이터 보호는 전적으로 스킴에 달려 있어요:

https:// — 연결이 TLS를 사용해요. 요청 본문(입력 텍스트, 프롬프트)과 요청 헤더의 api_key가 전송 중 암호화되고 공급자 인증서가 검증돼요. 원격 공급자에는 이것을 사용하세요.
http:// — 연결이 암호화되지 않아요. 요청 본문과 api_key가 평문으로 전송돼요. 사설 네트워크의 신뢰할 수 있는 공급자(예: 로컬 vLLM 또는 Ollama 인스턴스)에만 사용하세요.

기본적으로 AI 함수는 원격 호스트에 평문으로 데이터를 보내는 endpoint를 거부해요: 호스트가 루프백(localhost)이 아닌 비-HTTPS 엔드포인트는 예외를 발생시켜요. 루프백 호스트(localhost, 127.0.0.0/8, ::1)는 예외라서 로컬 http://localhost 모델 서버가 바로 동작해요. 원격 호스트에서 평문 http:// 엔드포인트를 허용하려면 ai_function_allow_insecure_endpoint를 1로 설정하세요. 이 검사는 remote_url_allow_hosts와 독립적이에요: That 설정은 호스트 허용 목록이고 URL 스킴을 검사하지 않으므로, 허용된 호스트를 가리키는 http:// 엔드포인트는 여전히 통과해요. 어느 경우든 TLS 종료 후에는 공급자가 입력 데이터를 평문으로 받게 됩니다. TLS는 서버와 공급자 사이의 네트워크 경로에서만 데이터를 보호해요.

지원 공급자 (Supported providers)

공급자	`provider` 값	채팅 함수	참고
OpenAI	`'openai'`	예	기본 공급자.
Anthropic	`'anthropic'`	예	`/v1/messages` 엔드포인트 사용.

관측성 (Observability)

AI 함수 활동은 ClickHouse ProfileEvents를 통해 추적돼요:

ProfileEvent	설명
`AIAPICalls`	AI 공급자에 보낸 HTTP 요청 수.
`AIInputTokens`	소비된 총 입력 토큰.
`AIOutputTokens`	소비된 총 출력 토큰.
`AIRowsProcessed`	결과를 받은 행 수.
`AIRowsSkipped`	건너뛴 행 수(쿼터 초과, 또는 `ai_function_throw_on_error = 0`으로 인한 오류).

aiClassify

LLM 공급자를 사용해 주어진 텍스트를 제공된 카테고리 중 하나로 분류해요. 자격 증명(공급자·모델·엔드포인트·선택적 API 키를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials 키에서 가져오고, 맵에 없으면 ai_function_text_default_credentials 설정에서 가져와요.

이 함수는 비결정적이에요: 같은 인자에 대해 다른 결과를 반환할 수 있어요.

구문 (Syntax)

aiClassify(text, categories[, params])

별칭 (Aliases): AIClassify

인자 (Arguments)

text — 분류할 텍스트. String
categories — 후보 카테고리 레이블의 상수 목록. Array(String)
params — 선택적 상수 Map(String, String) 매개변수. 함수별 키: temperature(무작위성을 제어하는 샘플링 온도; 기본 0.0), max_tokens(호출당 최대 출력 토큰; 기본 1024). 공통 매개변수 credentials와 model도 적용돼요. Map(String, String)

반환 값 (Returned value)

제공된 카테고리 레이블 중 하나, 또는 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우 컬럼 타입의 기본값(빈 문자열). String

예제 (Examples)

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

aiEmbed

구성된 AI 공급자를 사용해 주어진 텍스트의 임베딩 벡터를 생성해요. 이 함수는 텍스트를 구성된 임베딩 엔드포인트로 보내고 결과 벡터를 Array(Float32)로 반환해요. 행 블록 내에서 입력은 HTTP 요청당 최대 ai_function_embedding_max_batch_size 항목의 배치로 그룹화돼 호출당 오버헤드를 줄여요. 자격 증명은 매개변수 맵의 credentials 키 또는 ai_function_embedding_default_credentials 설정에서 가져와요. aiEmbed는 임베딩 엔드포인트가 채팅 엔드포인트와 다르므로 텍스트 함수와 별도의 기본 자격 증명 설정을 사용해요. model은 필수 위치 인자(상수 String)예요. 텍스트 함수와 달리 aiEmbed는 명명된 컬렉션이나 매개변수 맵에서 model을 읽지 않아요. model을 정의하는 명명된 컬렉션은 거부돼요. 선택적 dimensions 매개변수는 모델이 지원할 때(예: OpenAI의 text-embedding-3-*) 주어진 크기의 벡터를 요청하고, 그 외에는 모델 고유 크기를 반환해요.

구문 (Syntax)

aiEmbed(text, model[, params])

별칭 (Aliases): AIEmbed

인자 (Arguments)

text — 임베딩할 텍스트. String
model — 임베딩 모델 이름. const String
params — 선택적 상수 Map(String, String) 매개변수. 함수별 키: dimensions(출력 벡터의 목표 차원 수; 0 또는 생략은 모델 고유 크기). 공통 매개변수 credentials도 적용돼요. Map(String, String)

반환 값 (Returned value)

임베딩 벡터, 또는 입력이 NULL/비어 있거나, 요청이 실패하고 ai_function_throw_on_error가 비활성화되었거나, ai_function_throw_on_quota_exceeded가 비활성화된 상태에서 쿼터를 초과한 경우 빈 배열. Array(Float32)

예제 (Examples)

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))
SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

aiExtract

LLM 공급자를 사용해 비정형 텍스트에서 구조화된 정보를 추출해요. 세 번째 인자는 자유 형식 자연어 지침(예: 'the main complaint') 또는 '{"field_a": "description of field a", ...}' 형식의 JSON 인코딩 스키마일 수 있어요. 지침 모드에서는 추출된 값을 평문 문자열로 반환하고, 찾은 것이 없으면 빈 문자열을 반환해요. 스키마 모드에서는 요청된 스키마와 키가 일치하는 JSON 객체 문자열을 반환하며, 누락된 필드는 null이에요.

이 함수는 비결정적이에요.

구문 (Syntax)

aiExtract(text, instruction_or_schema[, params])

별칭 (Aliases): AIExtract

반환 값 (Returned value)

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

aiFilter

LLM 공급자를 사용해 주어진 텍스트에 대해 자연어 조건을 평가하고 WHERE, PREWHERE, JOIN ... ON에 적합한 불리언(UInt8)을 반환해요. 이 함수는 모델에게 소문자 true 또는 false만 응답하도록 요청해요. true 이외의 완전한 응답(false와 인식되지 않는 텍스트 포함)은 0으로 매핑되어 행이 필터링돼요. 공급자가 신호한 불완전한 응답(잘린 것, 콘텐츠 필터링, 추가 조치 필요)은 오류로 처리돼요: ai_function_throw_on_error가 활성화(기본값)되면 쿼리가 중단되고, 비활성화되면 행이 0으로 매핑되어 필터링돼요. 경고: aiFilter 결과를 검토 없이 신뢰하지 마세요. LLM 기반 조건은 부정확하거나 일관되지 않을 수 있어요. 오탐(false positive)과 부탐(false negative)이 허용되는 곳에서만 사용하세요. JOIN ... ON에서 aiFilter를 사용하면 후보 쌍마다 LLM을 한 번씩 평가하므로 비쌀 수 있어요.

이 함수는 비결정적이에요.

구문 (Syntax)

aiFilter(text, condition[, params])

별칭 (Aliases): AIFilter

반환 값 (Returned value)

텍스트가 조건과 일치하면 1, 그렇지 않으면 0. 요청이 실패하고 ai_function_throw_on_error가 비활성화되면 기본값(0)을 반환해요. UInt8

aiGenerate

LLM 공급자를 사용해 프롬프트에서 자유 형식 텍스트 콘텐츠를 생성해요. 이 함수는 프롬프트를 구성된 AI 공급자로 보내고 생성된 텍스트를 반환해요. 선택적 매개변수 맵은 system_prompt(모델의 동작을 안내하는 지침, 예: 톤, 형식, 역할), temperature, max_tokens, model도 설정할 수 있어요. system_prompt가 설정되지 않으면 기본값은: You are a helpful assistant. Provide a clear and concise response.

이 함수는 비결정적이에요.

구문 (Syntax)

aiGenerate(prompt[, params])

별칭 (Aliases): AIGenerate

인자 (Arguments)

prompt — 모델에 보낼 사용자 프롬프트 또는 질문. String
params — 선택적 상수 Map(String, String) 매개변수. 함수별 키: temperature(무작위성 제어; 기본 0.7), max_tokens(기본 1024), system_prompt(기본 일반 도우미 프롬프트). Map(String, String)

반환 값 (Returned value)

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

예제 (Examples)

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

aiRedact

LLM 공급자를 사용해 주어진 텍스트에서 개인 식별 정보(PII)를 탐지하고 삭제(redact)해요. aiRedact는 best-effort 방식으로 PII 탐지·삭제를 수행하며 출력은 신뢰할 수 없어요. PII가 탐지·제거되는지는 선택한 모델, 프롬프트, 입력에 따라 달라져요: 모델이 식별자를 놓치거나, 부분적으로만 삭제하거나, 주변 텍스트를 변경할 수 있어요. 잘 구성된 영어 텍스트에서 가장 잘 동작하며, 다른 언어나 철자·구두점·문법 오류가 많은 텍스트에서는 결과가 나빠질 수 있어요. aiRedact는 출력에 PII가 없다는 것을 보장하지 않으며, 그 자체로 안전하거나 충분한 익명화 메커니즘으로 취급해서는 안 돼요. 신뢰할 수 없는 당사자에게 데이터를 노출하기 전에 항상 출력을 검토해 조직의 데이터 개인정보 보호 및 규정 준수 정책을 충족하는지 확인하세요.

탐지된 각 PII 구간은 삭제 토큰으로 교체돼요(기본적으로 [REDACTED], replacement 매개변수로 구성 가능). categories 배열은 삭제할 PII 유형을 제한하며, 빈 배열은 공통 카테고리의 기본 집합(이름, 이메일, 전화번호, 주소, 신용카드, IP 주소)으로 대체돼요. aiRedact는 탐지된 PII 구간만 변경하도록 모델에 지시하지만 주변 텍스트 보존은 best-effort로, 모델이 여전히 변경할 수 있어요. 탭, 줄바꿈, 캐리지 리턴 이외의 제어 문자도 요청 전에 공백으로 정규화되므로, 출력은 그것들을 포함한 입력과 바이트 단위로 동일하지 않아요. aiRedact는 PII가 교체된 전체 입력 텍스트를 반환하므로 출력 길이는 입력과 거의 같아요. max_tokens(기본 1024)을 입력 길이(토큰)보다 높게 설정하세요. 너무 낮은 제한으로 잘린 응답은 부분적으로 삭제된 텍스트를 반환하지 않고 AI_PROVIDER_RESPONSE_TRUNCATED로 거부돼요(또는 ai_function_throw_on_error가 비활성화되면 컬럼 기본값을 산출).

이 함수는 비결정적이에요.

구문 (Syntax)

aiRedact(text, categories[, params])

별칭 (Aliases): AIRedact

반환 값 (Returned value)

탐지된 PII가 삭제 토큰으로 교체된 텍스트, 또는 요청이 실패하고 ai_function_throw_on_error가 비활성화되면 컬럼 타입의 기본값(빈 문자열). String

예제 (Examples)

SELECT aiRedact('Purchase was done by customer John Doe with email [email protected]', ['email', 'credit_card', 'name'])
-- Purchase was done by customer [REDACTED] with email [REDACTED]

aiSimilarity

구성된 임베딩 공급자를 사용해 두 텍스트의 의미론적 유사도를 계산해요. 두 텍스트의 벡터 임베딩을 계산하고 그 코사인 유사도를 반환해요. 반대되는 임베딩 벡터에는 -1 점수가 주어지며, 의미상으로는 -1에 가까운 점수의 텍스트가 반대 의미라는 뜻이에요. 0 점수는 벡터가 직교한다는 뜻, 즉 의미상 무관하다는 뜻이에요. 마지막으로 1 점수는 임베딩 벡터가 같은 방향을 가리킨다는 뜻으로, 1에 가까운 점수의 텍스트는 의미가 유사하다는 뜻이에요. 이는 동일한 임베딩에 대한 cosineDistance의 보수예요(aiSimilarity = 1 - cosineDistance(embedding1, embedding2)). 배칭, 자격 증명, dimensions 매개변수는 aiEmbed와 일치하며, ai_function_embedding_default_credentials 기본 자격 증명 설정을 포함해요. aiEmbed처럼 model은 필수 위치 인자(상수 String)이며 명명된 컬렉션이나 매개변수 맵에서 읽지 않아요.

구문 (Syntax)

aiSimilarity(text1, text2, model[, params])

별칭 (Aliases): AISimilarity

반환 값 (Returned value)

[-1, 1]의 코사인 유사도, 또는 두 텍스트 중 하나가 NULL/비어 있거나, 임베딩 요청이 실패하고 ai_function_throw_on_error가 비활성화되었거나, ai_function_throw_on_quota_exceeded가 비활성화된 상태에서 쿼터를 초과한 경우 NULL. Nullable(Float32)

aiTranslate

LLM 공급자를 사용해 주어진 텍스트를 지정된 목표 언어로 번역해요. 추가 스타일이나 방언 지침은 매개변수 맵의 instructions 키로 전달할 수 있어요(예: 'keep technical terms untranslated').

이 함수는 비결정적이에요.

구문 (Syntax)

aiTranslate(text, target_language[, params])

별칭 (Aliases): AITranslate

인자 (Arguments)

text — 번역할 텍스트. String
target_language — 목표 언어 이름 또는 BCP-47 코드(예: 'French', 'es-MX'). String
params — 선택적 상수 Map(String, String) 매개변수. 함수별 키: temperature(기본 0.3), max_tokens(기본 1024), instructions(번역자용 추가 스타일 또는 방언 지침). Map(String, String)

반환 값 (Returned value)

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

예제 (Examples)

SELECT aiTranslate('Hello, world!', 'French')  -- Bonjour le monde!

AI 함수

AI 함수 (AI Functions)

본문

구성 (Configuration)

명명된 컬렉션 매개변수 (Named collection parameters)

자격 증명 선택 (Selecting credentials)

매개변수 맵 (Parameter map)

쿼리 수준 설정 (Query-level settings)

엔드포인트 호스트 제한 (Restricting endpoint hosts)

전송 보안 (HTTP vs HTTPS)

지원 공급자 (Supported providers)

관측성 (Observability)

aiClassify

aiEmbed

aiExtract

aiFilter

aiGenerate

aiRedact

aiSimilarity

aiTranslate

더 알아보기 (Learn more)