ai_function_* 세션 설정

이 설정들은 ClickHouse의 AI 함수(aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact, aiEmbed, aiSimilarity 등)의 네트워크, 자격 증명, 호출 한도, 재시도 동작을 제어해요. ClickHouse 소스 코드에서 자동으로 생성된 세션 설정 문서예요.

출처: 문서

본문

이 설정들은 system.settings에서 사용할 수 있으며 소스 코드에서 자동으로 생성돼요.

ai_function_allow_insecure_endpoint

false(기본값)이면 AI 함수가 프롬프트와 API 키를 암호화되지 않은 연결로 원격 호스트에 보내는 named-collection endpoint 사용을 거부해요. 즉, 호스트가 루프백이 아닌 모든 비-HTTPS 엔드포인트는 예외와 함께 거부돼요. 루프백 엔드포인트(예: 로컬 http://localhost 모델 서버)는 항상 허용돼요. true로 설정하면 원격 호스트의 평문 http:// 엔드포인트를 허용해요.

ai_function_embedding_default_credentials

호출이 파라미터 맵에 credentials를 전달하지 않을 때 임베딩 함수(aiEmbed, aiSimilarity)가 사용하는 named collection의 이름이에요. 비어 있으면 기본값이 없다는 뜻으로, 그런 호출은 반드시 credentials를 명시적으로 전달해야 해요. 이 함수들은 model을 named collection이 아니라 필수 위치 인자로 받아요. 임베딩 엔드포인트는 채팅 엔드포인트와 다르므로 ai_function_text_default_credentials와 분리되어 있어요.

ai_function_embedding_max_batch_size

임베딩 함수(aiEmbed, aiSimilarity)가 단일 HTTP 요청에 포함하는 텍스트의 최대 개수예요. 텍스트는 이 크기의 배치로 그룹화되어 API 호출 오버헤드를 줄여요. 예를 들어 고유 텍스트 500개에 배치 크기 100이면 HTTP 요청 5개가 발생해요.

ai_function_max_api_calls_per_query

AI 함수가 쿼리당 보낼 수 있는 HTTP 요청의 최대 개수예요. 각 서버와 쿼리 조각에 독립적으로 적용돼요. 하나의 실행 컨텍스트 안에서는 모든 AI 함수·블록·스레드가 공유하는 정확한 상한이에요. 단, 분산 쿼리(샤드 또는 병렬 복제본 조각)는 조각당 이만큼의 요청을 보낼 수 있어요. 최상위 쿼리에서 설정해야 하며, 하위 쿼리 SETTINGS 오버라이드는 무시돼요. 0으로 설정하면 비활성화돼요.

ai_function_max_input_tokens_per_query

단일 쿼리의 모든 AI 함수 API 호출에 걸친 최대 총 입력(프롬프트) 토큰 수예요. 제공자 응답에서 누적 집계돼요. 호출의 입력 토큰은 응답이 도착할 때까지 알 수 없으므로, 이 한도는 진행 중(in-flight) 요청 하나분의 입력 토큰만큼 초과될 수 있다는 점을 참고해요. 다른 AI 할당량과 마찬가지로 서버/쿼리 조각별로 적용되며, 분산 쿼리에 걸쳐 합산되지 않고, 최상위 쿼리에서 설정해야 해요(하위 쿼리 SETTINGS 오버라이드는 무시). 0으로 설정하면 비활성화돼요.

이 한도는 응답에 usage 객체를 보고하는 제공자(OpenAI, Anthropic, vLLM)에만 적용돼요. 토큰 사용량을 생략하는 제공자(특히 HuggingFace TEI)는 카운터가 0으로 남으므로, 그런 호출은 ai_function_max_api_calls_per_query를 사용해 제한해요.

ai_function_max_output_tokens_per_query

단일 쿼리의 모든 AI 함수 API 호출에 걸친 최대 총 출력(completion) 토큰 수예요. 제공자 응답에서 누적 집계돼요. 호출의 출력 토큰은 응답이 도착할 때까지 알 수 없으므로, 이 한도는 진행 중 요청 하나분의 출력 토큰만큼 초과될 수 있다는 점을 참고해요. 다른 AI 할당량과 마찬가지로 서버/쿼리 조각별로 적용되며, 분산 쿼리에 걸쳐 합산되지 않고, 최상위 쿼리에서 설정해야 해요(하위 쿼리 SETTINGS 오버라이드는 무시). 0으로 설정하면 비활성화돼요.

이 한도는 응답에 usage 객체를 보고하는 제공자(OpenAI, Anthropic, vLLM)에만 적용돼요. 출력 토큰을 생성하지 않는 임베딩 함수(aiEmbed, aiSimilarity)에는 적용되지 않아요.

ai_function_max_retries

개별 API 요청의 일시적 오류에 대한 최대 재시도 횟수예요. 각 재시도는 ai_function_retry_initial_delay_ms부터 시작하는 지수 백오프(exponential backoff)를 사용해요.

ai_function_request_timeout_sec

AI 함수(AI 채팅 완성 및 임베딩 API 호출)가 만드는 개별 HTTP 요청의 타임아웃(초)이에요. 요청이 이 시간 안에 완료되지 않으면 실패로 간주되고 ai_function_max_retries에 따라 재시도될 수 있어요.

ai_function_retry_initial_delay_ms

실패한 AI 함수 API 요청의 첫 재시도 전 초기 지연(밀리초)이에요. 이후 시도마다 지연이 두 배로 증가해요(지수 백오프). 예를 들어 기본 설정에서: 1000ms, 2000ms, 4000ms.

ai_function_text_default_credentials

호출이 파라미터 맵에 credentials를 전달하지 않을 때 텍스트 AI 함수(aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact)가 사용하는 named collection의 이름이에요. 비어 있으면 기본값이 없다는 뜻으로, 그런 호출은 반드시 credentials를 명시적으로 전달해야 해요. 채팅-완성 엔드포인트는 임베딩 엔드포인트와 다르므로, 이 값은 ai_function_embedding_default_credentials와 분리되어 있어요.

ai_function_throw_on_error

true(기본값)이면 모든 재시도를 소진한 후 영구적으로 실패한 AI 함수 호출이 예외로 쿼리를 중단해요. false이면 실패한 행이 열 타입의 기본값(String이면 빈 문자열)을 받고 처리가 계속돼요.

ai_function_throw_on_quota_exceeded

true(기본값)이면 AI 함수 할당량 한도(ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query, 또는 ai_function_max_api_calls_per_query) 초과 시 예외로 쿼리를 중단해요. false이면 나머지 행이 열 타입의 기본값(String이면 빈 문자열)을 받아요. 할당량 한도와 마찬가지로 최상위 쿼리에서 설정해야 하며, 하위 쿼리 SETTINGS 오버라이드는 무시돼요.

ai_function_* 세션 설정