AI 함수 - ClickHouse Documentation

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

AI 함수는 실험적 기능입니다. 이를 활성화하려면 allow_experimental_ai_functions을 설정하십시오.

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

모든 함수는 다음을 제공하는 공통 인프라를 기반으로 합니다:

Quota 적용: 토큰에 대한 쿼리별 제한(ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query) 및 API 호출 제한(ai_function_max_api_calls_per_query).
백오프를 사용하는 재시도: 일시적인 실패는 지수형 백오프(ai_function_retry_initial_delay_ms)를 적용하여 재시도됩니다(ai_function_max_retries).

구성

AI 함수는 프로바이더 자격 증명과 구성을 저장하는 명명된 컬렉션을 참조합니다. 서로 다른 함수 또는 함수 호출마다 서로 다른 명명된 컬렉션을 생성해 사용할 수 있습니다. 예를 들어 텍스트 함수(aiGenerate, aiClassify, aiExtract, aiaiTranslate)에 사용할 명명된 컬렉션과 aiEmbed 함수에 사용할 명명된 컬렉션을 별도로 정의할 수 있습니다. 각 함수는 서로 다른 엔드포인트가 필요하며, 일반적으로 사용하는 모델도 다릅니다. 프로바이더 자격 증명을 포함하는 명명된 컬렉션을 생성하는 예시 구문은 다음과 같습니다. 하나는 채팅 엔드포인트용이고, 다른 하나는 임베딩 엔드포인트용입니다:

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

-- `aiEmbed` does not read `model` from the named collection; pass it as a positional argument instead.
-- Defining `model` in an `aiEmbed` 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-...';

명명된 컬렉션 매개변수

매개변수	유형	기본값	설명
`provider`	String	—	모델 프로바이더입니다. 지원값: `'openai'`, `'anthropic'`. 아래 참고를 확인하십시오.
`endpoint`	String	—	API endpoint URL입니다.
`model`	String	—	모델 이름입니다(예: `'gpt-4o-mini'`). 텍스트 Functions에서 사용됩니다. `aiEmbed`는 위치 인수로 `model`이 필요하며, 명명된 컬렉션에 `model`이 지정된 경우 오류가 발생합니다.
`api_key`	String	—	프로바이더 authentication 키입니다. 선택 사항: 생략하면 auth header가 전송되지 않으므로 authentication이 필요하지 않은 OpenAI 호환 server를 대상으로 지정할 수 있습니다.
`max_tokens`	UInt64	`1024`	API 호출당 최대 출력 token 수입니다.
`api_version`	String	—	API 버전 문자열입니다. Anthropic에서 사용됩니다(`'2023-06-01'`).

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

자격 증명 선택

함수는 다음 순서대로 사용할 명명된 컬렉션을 결정합니다.

있는 경우 매개변수 맵의 credentials 키
그렇지 않으면 해당 기본 자격 증명 설정:
- 텍스트 함수(aiGenerate, aiClassify, aiExtract, aiTranslate)의 경우 ai_function_text_default_credentials
- aiEmbed의 경우 ai_function_embedding_default_credentials

둘 다 설정되지 않으면 호출은 실패합니다. chat-completions 엔드포인트는 embeddings용 엔드포인트와 다르므로, 텍스트 함수와 임베딩 함수는 서로 다른 기본 설정을 사용합니다.

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'));

매개변수 맵

각 함수는 선택적으로 끝에 Map(String, String) 형식의 매개변수 맵을 받을 수 있습니다. 모든 값은 문자열이므로 숫자도 '0.2'처럼 따옴표로 감싸야 합니다. 알 수 없는 키는 허용되지 않습니다. 키가 있으면 해당 명명된 컬렉션 값을 재정의하고, 키가 없으면 명명된 컬렉션(model/max_tokens의 경우) 또는 내장 기본값이 사용됩니다. 예외는 aiEmbed로, model을 필수 위치 인수로 받으며(aiEmbed(text, model[, params])), 이를 매개변수 맵이나 명명된 컬렉션에 대신 설정하면 오류가 발생합니다. 다음 매개변수는 모든 AI 함수에 공통입니다:

Key	Description
`credentials`	사용할 명명된 컬렉션입니다(위 참조).
`model`	컬렉션의 `model`을 재정의합니다(텍스트 함수에만 해당하며, `aiEmbed`는 `model`을 맵 키가 아니라 필수 위치 인수로 받습니다).

개별 함수는 함수별 추가 매개변수(max_tokens, temperature, system_prompt, instructions, dimensions 등)를 지원합니다. 허용되는 매개변수와 해당 기본값은 아래 각 함수의 참고 문서를 참조하십시오.

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

쿼리 수준 설정

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

`endpoint` 호스트 제한

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

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

이 설정은 서버 전체에 적용되며 HTTP를 사용하는 모든 기능에 영향을 미친다는 점에 유의하십시오.

전송 보안(HTTP vs HTTPS)

전송 방식은 전적으로 endpoint URL의 스킴에 따라 결정됩니다. 요청 payload에는 애플리케이션 수준의 암호화가 없으므로, 전송 중 데이터 보호는 전적으로 스킴에 달려 있습니다.

https:// — 연결에 TLS를 사용합니다. 요청 본문(입력 텍스트, 프롬프트)과 요청 headers의 api_key는 전송 중 암호화되며, 프로바이더의 certificate도 검증됩니다. 원격 프로바이더를 사용할 때는 항상 이 방식을 사용하십시오.
http:// — 연결이 암호화되지 않습니다. 요청 본문과 api_key가 평문으로 전송됩니다. 신뢰할 수 있는 프로바이더가 프라이빗 네트워크에 있는 경우(예: 로컬 vLLM 또는 Ollama instance)에만 사용하십시오.

AI 함수는 HTTPS를 강제하지 않습니다. http:// 엔드포인트도 허용되며, 데이터는 암호화되지 않은 상태로 전송됩니다. 현재 평문 AI 엔드포인트를 거부하는 서버 측 설정은 없습니다. remote_url_allow_hosts는 대상 host만 제한하고 URL 스킴은 검사하지 않으므로, 허용된 host를 가리키는 http:// 엔드포인트도 그대로 허용됩니다. 암호화된 전송을 보장하려면 https:// 엔드포인트를 사용하는 이름이 지정된 컬렉션을 구성하십시오. 어느 경우든 프로바이더는 TLS 종료 이후 입력 데이터를 평문으로 받습니다. TLS는 server와 프로바이더 사이의 네트워크 경로에서만 데이터를 보호합니다.

지원되는 프로바이더

프로바이더	`provider` 값	채팅 함수	참고
OpenAI	`'openai'`	예	기본 프로바이더입니다.
Anthropic	`'anthropic'`	예	`/v1/messages` endpoint를 사용합니다.

관측성

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 스키마 응답 포맷과 함께 전송하여 모델이 제공된 레이블 중 정확히 하나만 반환하도록 제한합니다. 응답이 JSON 객체 {"category": "..."} 형태로 반환되면 레이블을 추출해 레이블 문자열을 반환합니다. 자격 증명(프로바이더, 모델, endpoint와 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials 키에서 가져오며, 맵에 이 키가 없으면 ai_function_text_default_credentials 설정에서 가져옵니다. 구문

aiClassify(text, categories[, params])

별칭: AIClassify 인수

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

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

Query

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

Response

positive

명시적 자격 증명을 사용해 컬럼 분류

Query

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

aiEmbed

도입 버전: v26.6.0 구성된 AI 프로바이더를 사용하여 지정된 텍스트의 임베딩 벡터를 생성합니다. 이 함수는 텍스트를 구성된 임베딩 endpoint로 전송하고, 결과 벡터를 Array(Float32)로 반환합니다. 단일 block의 행 내에서는 호출별 overhead를 줄이기 위해 입력이 HTTP request당 최대 ai_function_embedding_max_batch_size 개 항목의 batch로 그룹화됩니다. 자격 증명(프로바이더, endpoint, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 매개변수 맵의 credentials 키에서 가져오며, 맵에서 이를 생략한 경우 ai_function_embedding_default_credentials 설정에서 가져옵니다. 임베딩 endpoint는 chat endpoint와 다르므로 aiEmbed는 텍스트 함수와 별도의 기본 자격 증명 설정을 사용한다는 점에 유의하십시오. model은 필수 위치 인수(상수 String)입니다. 텍스트 함수와 달리 aiEmbed는 명명된 컬렉션이나 매개변수 맵에서 model을 읽지 않습니다. model을 정의하는 명명된 컬렉션은 조용히 무시되는 대신 거부됩니다. 선택적 dimensions 매개변수는 모델이 이를 지원하는 경우(예: OpenAI’s text-embedding-3-*) 지정한 크기의 벡터를 요청하며, 그렇지 않으면 모델의 네이티브 크기가 반환됩니다. 구문

aiEmbed(text, model[, params])

인수

text — 임베딩할 텍스트입니다. String
model — 임베딩 모델 이름입니다. const String
params — 선택적 상수 Map(String, String) 파라미터입니다. 함수별 키는 dimensions입니다(출력 벡터의 대상 차원 수이며, 0이거나 생략하면 모델의 네이티브 크기를 의미합니다). 공통 매개변수 credentials도 적용됩니다(AI 함수 참조). Map(String, String)

반환 값 임베딩 벡터 또는 빈 배열을 반환합니다. 입력이 NULL이거나 비어 있는 경우, 요청이 실패했지만 ai_function_throw_on_error가 비활성화된 경우, 또는 할당량을 초과했지만 ai_function_throw_on_quota_exceeded가 비활성화된 경우에는 빈 배열이 반환됩니다. Array(Float32) 예시 단일 문자열 임베딩(ai_function_embedding_default_credentials 설정이 지정된 경우 credentials는 생략할 수 있습니다)

Query

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

차원을 명시적으로 지정하는 경우

Query

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

텍스트 컬럼 임베드하기

Query

SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '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 인코딩 스키마일 수 있습니다. 지시문 모드에서 이 함수는 추출된 값을 일반 문자열로 반환하고, 아무것도 찾지 못하면 빈 문자열을 반환합니다. 스키마 모드에서 이 함수는 키가 요청한 스키마와 일치하는 JSON 객체 문자열을 반환하며, 누락된 필드는 null로 반환됩니다. 자격 증명(프로바이더, 모델, endpoint 및 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials key에서 가져오며, map에 이 항목이 없으면 ai_function_text_default_credentials setting에서 가져옵니다. 구문

aiExtract(text, instruction_or_schema[, params])

별칭: AIExtract 인수

text — 정보를 추출할 텍스트입니다. String
instruction_or_schema — 자유 형식의 추출 지침 또는 추출할 필드를 설명하는 상수 JSON 객체입니다. const String
params — 선택 사항인 상수 Map(String, String) 파라미터입니다. 함수별 키는 temperature(무작위성을 제어하는 샘플링 온도, 기본값 0.0)와 max_tokens(호출당 최대 출력 토큰 수, 기본값 1024)입니다. 공통 매개변수 credentials 및 model도 적용됩니다(AI 함수 참조). Map(String, String)

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

Query

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

Response

late and damaged package

스키마 추출

Query

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

aiGenerate

도입된 버전: v26.4.0 LLM 프로바이더를 사용해 프롬프트로부터 자유 형식의 텍스트 콘텐츠를 생성합니다. 이 함수는 프롬프트를 설정된 AI 프로바이더로 전송하고, 생성된 텍스트를 반환합니다. 자격 증명(프로바이더, 모델, endpoint, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials 키에서 가져오며, 맵에 해당 항목이 없으면 ai_function_text_default_credentials 설정에서 가져옵니다. 선택적 매개변수 맵에서는 system_prompt(어조, 포맷, 역할 등 모델의 동작을 안내하는 지시문), temperature, max_tokens, model도 설정할 수 있습니다. system_prompt가 설정되지 않으면 기본값은 다음과 같습니다: You are a helpful assistant. Provide a clear and concise response. 구문

aiGenerate(prompt[, params])

별칭: AIGenerate 인수

prompt — 모델에 보낼 사용자 프롬프트 또는 질문입니다. String
params — 선택적 상수 Map(String, String) 매개변수 맵입니다. 함수별 키는 다음과 같습니다: temperature (무작위성을 제어하는 샘플링 온도, 기본값 0.7), max_tokens (호출당 최대 출력 토큰 수, 기본값 1024), system_prompt (모델 동작을 안내하는 상수 시스템 수준 지침, 기본값은 일반적인 어시스턴트 프롬프트). 공통 매개변수인 credentials와 model도 적용됩니다(AI 함수 참조). Map(String, String)

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

Query

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

Response

명시적 자격 증명과 시스템 프롬프트 사용

Query

SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.'))

컬럼 값 요약

Query

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

aiTranslate

도입 버전: v26.4.0 주어진 텍스트를 LLM 프로바이더를 사용해 지정된 대상 언어로 번역합니다. 추가 스타일 또는 방언 관련 지침은 매개변수 맵의 instructions 키를 통해 전달할 수 있습니다(예: '기술 용어는 번역하지 않음'). 자격 증명(프로바이더, model, endpoint, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials 키에서 가져오며, 맵에 해당 항목이 없으면 ai_function_text_default_credentials 설정에서 가져옵니다. 구문

aiTranslate(text, target_language[, params])

별칭: AITranslate 인수

text — 번역할 텍스트입니다. String
target_language — 대상 언어 이름 또는 BCP-47 코드입니다(예: 'French', 'es-MX'). String
params — 선택적 상수 Map(String, String) 매개변수입니다. 함수별 키는 다음과 같습니다. temperature(무작위성을 제어하는 샘플링 온도, 기본값 0.3), max_tokens(호출당 최대 출력 토큰 수, 기본값 1024), instructions(번역기에 대한 추가 스타일 또는 방언 지침). 공통 매개변수인 credentials와 model도 적용됩니다(AI Functions 참조). Map(String, String)

반환 값 번역된 텍스트를 반환합니다. 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. String 예시 프랑스어로 번역

Query

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

Response

Bonjour le monde!

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

Query

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

​구성

​명명된 컬렉션 매개변수

​자격 증명 선택

​매개변수 맵

​쿼리 수준 설정

​endpoint 호스트 제한

​전송 보안(HTTP vs HTTPS)

​지원되는 프로바이더

​관측성

​aiClassify

​aiEmbed

​aiExtract

​aiGenerate

​aiTranslate

구성

명명된 컬렉션 매개변수

자격 증명 선택

매개변수 맵

쿼리 수준 설정

`endpoint` 호스트 제한

전송 보안(HTTP vs HTTPS)

지원되는 프로바이더

관측성

aiClassify

aiEmbed

aiExtract

aiGenerate

aiTranslate