> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > AI 함수 문서 # AI 함수 AI 함수는 ClickHouse에 내장된 함수로, AI를 호출하거나 임베딩을 생성해 데이터를 활용하고, 정보를 추출하고, 데이터를 분류하는 등의 작업에 사용할 수 있습니다... AI 함수는 실험적 기능입니다. 이를 활성화하려면 [`allow_experimental_ai_functions`](/ko/reference/settings/session-settings/allow-experimental#allow_experimental_ai_functions)을 설정하십시오. AI 함수는 예측하기 어려운 출력을 반환할 수 있습니다. 결과는 프롬프트의 품질과 사용된 모델에 크게 좌우됩니다. **프롬프트 인젝션** 입력 텍스트는 모델로 전송되며 모델의 출력을 유도할 수 있습니다(프롬프트 인젝션). 외부의 검증되지 않았거나 정제되지 않은 출처의 텍스트에는 모델이 공격자가 제어하는 콘텐츠를 반환하게 하거나, 요청된 형식을 무시하거나, 악성 페이로드를 출력하게 하는 지침이 포함될 수 있습니다. AI 함수 출력은 신뢰할 수 없는 것으로 간주하십시오. SQL 작성, 셸 명령, 추가 쿼리 또는 액세스 제어 결정과 같은 후속 단계에서 사용하기 전에 이를 검증하거나 정제하십시오. 모든 함수는 다음을 제공하는 공통 인프라를 기반으로 합니다: * **Quota 적용**: 토큰에 대한 쿼리별 제한([`ai_function_max_input_tokens_per_query`](/ko/reference/settings/session-settings/ai-function#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/ko/reference/settings/session-settings/ai-function#ai_function_max_output_tokens_per_query)) 및 API 호출 제한([`ai_function_max_api_calls_per_query`](/ko/reference/settings/session-settings/ai-function#ai_function_max_api_calls_per_query)). * **백오프를 사용하는 재시도**: 일시적인 실패는 지수형 백오프([`ai_function_retry_initial_delay_ms`](/ko/reference/settings/session-settings/ai-function#ai_function_retry_initial_delay_ms))를 적용하여 재시도됩니다([`ai_function_max_retries`](/ko/reference/settings/session-settings/ai-function#ai_function_max_retries)).
## 구성
AI 함수는 프로바이더 자격 증명과 구성을 저장하는 **명명된 컬렉션**을 참조합니다. 서로 다른 함수 또는 함수 호출마다 서로 다른 명명된 컬렉션을 생성해 사용할 수 있습니다. 예를 들어 텍스트 함수(`aiGenerate`, `aiClassify`, `aiFilter`, `aiExtract`, `aiTranslate`, `aiRedact`)에 사용할 명명된 컬렉션과 임베딩 함수(`aiEmbed`, `aiSimilarity`)에 사용할 명명된 컬렉션을 별도로 정의할 수 있습니다. 각 함수는 서로 다른 엔드포인트가 필요하며, 일반적으로 사용하는 모델도 다릅니다. 프로바이더 자격 증명을 포함하는 명명된 컬렉션을 생성하는 예시 구문은 다음과 같습니다. 하나는 채팅 엔드포인트용이고, 다른 하나는 임베딩 엔드포인트용입니다: ```sql theme={null} 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-...'; ```
### 명명된 컬렉션 매개변수
| 매개변수 | 유형 | 기본값 | 설명 | | ------------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `provider` | String | — | 모델 프로바이더입니다. 지원값: `'openai'`, `'anthropic'`. 아래 참고를 확인하십시오. | | `endpoint` | String | — | API 엔드포인트 URL입니다. | | `model` | String | — | 모델 이름입니다(예: `'gpt-4o-mini'`). 텍스트 함수에서 사용됩니다. 임베딩 함수(`aiEmbed`, `aiSimilarity`)는 위치 인수로 `model`이 필요하며, 명명된 컬렉션에 `model`이 지정된 경우 오류가 발생합니다. | | `api_key` | String | — | 프로바이더 authentication 키입니다. 선택 사항: 생략하면 auth header가 전송되지 않으므로 authentication이 필요하지 않은 OpenAI 호환 server를 대상으로 지정할 수 있습니다. | | `max_tokens` | UInt64 | `1024` | API 호출당 최대 출력 토큰 수입니다. | | `api_version` | String | — | API 버전 문자열입니다. Anthropic에서 사용됩니다(`'2023-06-01'`). | `provider = 'openai'`로 설정하고 `endpoint`가 해당 서비스를 가리키도록 지정하면 모든 OpenAI 호환 API(예: vLLM, Ollama, LiteLLM)를 사용할 수 있습니다.
### 자격 증명 선택
함수는 다음 순서대로 사용할 명명된 컬렉션을 결정합니다. 1. 있는 경우 매개변수 맵의 `credentials` 키 2. 그렇지 않으면 해당 기본 자격 증명 설정: * 텍스트 함수(`aiGenerate`, `aiClassify`, `aiFilter`, `aiExtract`, `aiTranslate`, `aiRedact`)의 경우 [`ai_function_text_default_credentials`](/ko/reference/settings/session-settings/ai-function#ai_function_text_default_credentials) * 임베딩 함수(`aiEmbed`, `aiSimilarity`)의 경우 [`ai_function_embedding_default_credentials`](/ko/reference/settings/session-settings/ai-function#ai_function_embedding_default_credentials) 둘 다 설정되지 않으면 호출은 실패합니다. chat-completions 엔드포인트는 embeddings용 엔드포인트와 다르므로, 텍스트 함수와 임베딩 함수는 서로 다른 기본 설정을 사용합니다. ```sql theme={null} 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')); ``` `UInt8`을 반환하고 `WHERE`에서 직접 사용할 수 있는 `aiFilter`를 사용하여 자연어 조건으로 행을 필터링합니다: ```sql theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping'); ```
### 매개변수 맵
각 함수는 선택적으로 끝에 `Map(String, String)` 형식의 매개변수 맵을 받을 수 있습니다. 모든 값은 문자열이므로 숫자도 `'0.2'`처럼 따옴표로 감싸야 합니다. 알 수 없는 키는 허용되지 않습니다. 키가 있으면 해당 명명된 컬렉션 값을 재정의하고, 키가 없으면 명명된 컬렉션(`model`/`max_tokens`의 경우) 또는 내장 기본값이 사용됩니다. 예외는 임베딩 함수(`aiEmbed`, `aiSimilarity`)로, `model`을 필수 위치 인수로 받으며(예: `aiEmbed(text, model[, params])`, `aiSimilarity(text1, text2, model[, params])`), 이를 매개변수 맵이나 명명된 컬렉션에 대신 설정하면 오류가 발생합니다. 이는 재현 가능한 임베딩을 보장하기 위한 것입니다. 다음 매개변수는 모든 AI 함수에 공통입니다: | Key | Description | | ------------- | --------------------------------------------------------------------------------------------------------- | | `credentials` | 사용할 명명된 컬렉션입니다(위 참조). | | `model` | 컬렉션의 `model`을 재정의합니다(텍스트 함수에만 해당하며, 임베딩 함수(`aiEmbed`, `aiSimilarity`)는 `model`을 맵 키가 아니라 필수 위치 인수로 받습니다). | 개별 함수는 함수별 추가 매개변수(`max_tokens`, `temperature`, `system_prompt`, `instructions`, `dimensions` 등)를 지원합니다. 허용되는 매개변수와 해당 기본값은 아래 각 함수의 참고 문서를 참조하십시오. ```sql theme={null} SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles; ```
### 쿼리 수준 설정
모든 AI 관련 설정은 [설정](/ko/reference/settings/session-settings) 문서에서 `ai_function_` 접두사 아래에 나열되어 있습니다.
### `엔드포인트` 호스트 제한
AI 명명된 컬렉션의 `엔드포인트` URL은 서버가 자체 아이덴티티로 연결하는 아웃바운드 대상입니다. 이때 요청 헤더에는 지정된 경우 명명된 컬렉션의 `api_key`가 포함될 수 있습니다. 기본적으로 ClickHouse는 모든 호스트를 허용합니다. 함수를 특정 프로바이더 집합으로 제한하려면 서버 config에서 [`remote_url_allow_hosts`](/ko/reference/settings/server-settings/settings/remote#remote_url_allow_hosts)를 구성하십시오. 예: ```xml theme={null} api.openai.com api.anthropic.com ``` 이 설정은 서버 전체에 적용되며 HTTP를 사용하는 모든 기능에 영향을 미친다는 점에 유의하십시오.
### 전송 보안(HTTP vs HTTPS)
전송 방식은 전적으로 `endpoint` URL의 스킴에 따라 결정됩니다. 요청 payload에는 애플리케이션 수준의 암호화가 없으므로, 전송 중 데이터 보호는 전적으로 스킴에 달려 있습니다. * `https://` — 연결에 TLS를 사용합니다. 요청 본문(입력 텍스트, 프롬프트)과 요청 headers의 `api_key`는 전송 중 암호화되며, 프로바이더의 certificate도 검증됩니다. 원격 프로바이더를 사용할 때는 항상 이 방식을 사용하십시오. * `http://` — 연결이 **암호화되지 않습니다**. 요청 본문과 `api_key`가 평문으로 전송됩니다. 신뢰할 수 있는 프로바이더가 프라이빗 네트워크에 있는 경우(예: 로컬 `vLLM` 또는 `Ollama` instance)에만 사용하십시오. 기본적으로 AI 함수는 원격 host로 데이터를 평문으로 전송하는 `endpoint`를 거부합니다. host가 루프백이 아닌 HTTPS 이외의 모든 엔드포인트는 예외를 발생시킵니다. 루프백 host(`localhost`, `127.0.0.0/8`, `::1`)는 예외이므로 로컬 `http://localhost` 모델 server는 별도 설정 없이 작동합니다. 원격 host에서 평문 `http://` 엔드포인트를 허용하려면 [`ai_function_allow_insecure_endpoint`](/ko/reference/settings/session-settings/ai-function#ai_function_allow_insecure_endpoint)를 `1`로 설정하십시오. 이 검사는 [`remote_url_allow_hosts`](/ko/reference/settings/server-settings/settings/remote#remote_url_allow_hosts)와 독립적입니다. 이 설정은 host allowlist이며 URL 스킴은 검사하지 않으므로, 허용된 host를 가리키는 `http://` 엔드포인트도 이 검사를 통과합니다. 어느 경우든 프로바이더는 TLS 종료 이후 입력 데이터를 평문으로 받습니다. TLS는 server와 프로바이더 사이의 네트워크 경로에서만 데이터를 보호합니다.
## 지원되는 프로바이더
| 프로바이더 | `provider` 값 | 채팅 함수 | 참고 | | --------- | ------------- | ----- | ------------------------------- | | OpenAI | `'openai'` | 예 | 기본 프로바이더입니다. | | Anthropic | `'anthropic'` | 예 | `/v1/messages` endpoint를 사용합니다. |
## 관측성
AI 함수 활동은 ClickHouse [ProfileEvents](/ko/reference/system-tables/query_log)를 통해 추적됩니다. | ProfileEvent | Description | | ----------------- | ------------------------------------------------------------------------ | | `AIAPICalls` | AI 프로바이더로 전송된 HTTP 요청 수입니다. | | `AIInputTokens` | 사용된 총 입력 토큰 수입니다. | | `AIOutputTokens` | 사용된 총 출력 토큰 수입니다. | | `AIRowsProcessed` | 결과를 받은 행 수입니다. | | `AIRowsSkipped` | 건너뛴 행 수입니다(QUOTA를 초과했거나 `ai_function_throw_on_error = 0`일 때 오류가 발생한 경우). | 다음과 같이 이 이벤트를 조회합니다. ```sql theme={null} 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 프로바이더를 사용해 주어진 텍스트를 제공된 범주 중 하나로 분류합니다. 자격 증명(프로바이더, 모델, endpoint와 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 `credentials` 키에서 가져오며, 맵에 이 키가 없으면 `ai_function_text_default_credentials` 설정에서 가져옵니다. **구문** ```sql theme={null} aiClassify(text, categories[, params]) ``` **별칭**: `AIClassify` **인수** * `text` — 분류할 텍스트입니다. [`String`](/ko/reference/data-types/string) * `categories` — 후보 카테고리 레이블의 상수 목록입니다. [`Array(String)`](/ko/reference/data-types/array) * `params` — 선택적 상수 `Map(String, String)` 매개변수입니다. 함수별 키는 `temperature`(무작위성을 제어하는 샘플링 온도, 기본값 `0.0`), `max_tokens`(호출당 최대 출력 토큰 수, 기본값 `1024`)입니다. 공통 매개변수 `credentials` 및 `model`도 적용됩니다([AI 함수](/ko/reference/functions/regular-functions/ai-functions) 참고). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** 제공된 카테고리 레이블 중 하나를 반환합니다. 요청이 실패하고 `ai_function_throw_on_error`가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. [`String`](/ko/reference/data-types/string) **예시** **감정 분류** ```sql title=Query theme={null} SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']) ``` ```response title=Response theme={null} positive ``` **명시적 자격 증명을 사용해 컬럼 분류** ```sql title=Query theme={null} SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5 ```
## aiEmbed
도입 버전: v26.6.0 구성된 AI 프로바이더를 사용하여 지정된 텍스트의 임베딩 벡터를 생성합니다. 이 함수는 텍스트를 구성된 임베딩 엔드포인트로 전송하고, 결과 벡터를 `Array(Float32)`로 반환합니다. 단일 block의 행 내에서는 호출별 overhead를 줄이기 위해 입력이 HTTP 요청당 최대 [`ai_function_embedding_max_batch_size`](/ko/reference/settings/session-settings/ai-function#ai_function_embedding_max_batch_size) 개 항목의 batch로 그룹화됩니다. 자격 증명(프로바이더, 엔드포인트, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 매개변수 맵의 `credentials` 키에서 가져오며, 맵에서 이를 생략한 경우 `ai_function_embedding_default_credentials` 설정에서 가져옵니다. 임베딩 엔드포인트는 chat 엔드포인트와 다르므로 `aiEmbed`는 텍스트 함수와 별도의 기본 자격 증명 설정을 사용한다는 점에 유의하십시오. `model`은 필수 위치 인수(상수 `String`)입니다. 텍스트 함수와 달리 `aiEmbed`는 명명된 컬렉션이나 매개변수 맵에서 `model`을 읽지 않습니다. `model`을 정의하는 명명된 컬렉션은 거부됩니다. 선택적 `dimensions` 매개변수는 모델이 이를 지원하는 경우(예: OpenAI's `text-embedding-3-*`) 지정한 크기의 벡터를 요청하며, 그렇지 않으면 모델의 네이티브 크기가 반환됩니다. **구문** ```sql theme={null} aiEmbed(text, model[, params]) ``` **별칭**: `AIEmbed` **인수** * `text` — 임베딩할 텍스트입니다. [`String`](/ko/reference/data-types/string) * `model` — 임베딩 모델 이름입니다. [`const String`](/ko/reference/data-types/string) * `params` — 선택적 상수 `Map(String, String)` 매개변수입니다. 함수별 키는 `dimensions`입니다(출력 벡터의 대상 차원 수이며, `0`이거나 생략하면 모델의 네이티브 크기를 의미합니다). 공통 매개변수 `credentials`도 적용됩니다([AI 함수](/ko/reference/functions/regular-functions/ai-functions) 참조). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** 임베딩 벡터 또는 빈 배열을 반환합니다. 입력이 NULL이거나 비어 있는 경우, 요청이 실패했지만 `ai_function_throw_on_error`가 비활성화된 경우, 또는 QUOTA를 초과했지만 `ai_function_throw_on_quota_exceeded`가 비활성화된 경우에는 빈 배열이 반환됩니다. [`Array(Float32)`](/ko/reference/data-types/array) **예시** **단일 문자열 임베딩(`ai_function_embedding_default_credentials` 설정이 지정된 경우 `credentials`는 생략할 수 있습니다)** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **차원을 명시적으로 지정하는 경우** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) ``` **텍스트 컬럼 임베드하기** ```sql title=Query theme={null} 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에서 가져옵니다. **구문** ```sql theme={null} aiExtract(text, instruction_or_schema[, params]) ``` **별칭**: `AIExtract` **인수** * `text` — 정보를 추출할 텍스트입니다. [`String`](/ko/reference/data-types/string) * `instruction_or_schema` — 자유 형식의 추출 지침 또는 추출할 필드를 설명하는 상수 JSON 객체입니다. [`const String`](/ko/reference/data-types/string) * `params` — 선택 사항인 상수 `Map(String, String)` 파라미터입니다. 함수별 키는 `temperature`(무작위성을 제어하는 샘플링 온도, 기본값 `0.0`)와 `max_tokens`(호출당 최대 출력 토큰 수, 기본값 `1024`)입니다. 공통 매개변수 `credentials` 및 `model`도 적용됩니다([AI 함수](/ko/reference/functions/regular-functions/ai-functions) 참조). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** 단일 추출 값(지침 모드) 또는 JSON 객체 문자열(스키마 모드)입니다. 요청이 실패하고 `ai_function_throw_on_error`가 비활성화되어 있으면 컬럼 타입의 기본값(빈 문자열)을 반환합니다. [`String`](/ko/reference/data-types/string) **예시** **자유 형식 추출 지침** ```sql title=Query theme={null} SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint') ``` ```response title=Response theme={null} late and damaged package ``` **스키마 추출** ```sql title=Query theme={null} SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5 ```
## aiFilter
도입 버전: v26.8.0 LLM 프로바이더를 사용하여 지정된 텍스트에 자연어 조건을 적용하고, `WHERE`, `PREWHERE`, `JOIN ... ON`에 사용할 수 있는 Boolean(`UInt8`) 값을 반환합니다. 이 FUNCTION은 모델이 소문자 `true` 또는 `false`로만 응답하도록 요청합니다. 실패한 request(`ai_function_throw_on_error`가 비활성화된 경우)와 인식할 수 없는 응답은 `0`으로 매핑되므로 해당 행은 필터링됩니다. **Warning:** 면밀히 검토하지 않은 `aiFilter` 결과를 신뢰하지 마십시오. LLM 기반 프레디케이트는 부정확하거나 일관되지 않을 수 있으므로 false positive와 false negative를 허용할 수 있는 경우에만 사용하십시오. 자격 증명(LLM 프로바이더, 모델, 엔드포인트 및 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 `credentials` key에서 가져오며, 맵에 해당 항목이 없으면 `ai_function_text_default_credentials` SETTING에서 가져옵니다. Note: `JOIN ... ON`에서 `aiFilter`를 사용하면 candidate 쌍마다 LLM을 한 번씩 평가하므로 비용이 많이 들 수 있습니다. **구문** ```sql theme={null} aiFilter(text, condition[, params]) ``` **별칭**: `AIFilter` **인수** * `text` — 평가할 텍스트입니다. [`String`](/ko/reference/data-types/string) * `condition` — 텍스트가 충족해야 하는 상수 자연어 조건입니다. [`String`](/ko/reference/data-types/string) * `params` — 선택적으로 지정하는 상수 `Map(String, String)` 매개변수입니다. 함수별 키는 다음과 같습니다. `temperature`(무작위성을 제어하는 샘플링 온도, 기본값 `0.0`), `max_tokens`(호출당 최대 출력 토큰 수, 기본값 `1024`). 공통 매개변수인 `credentials` 및 `model`도 적용됩니다([AI 함수](/ko/reference/functions/regular-functions/ai-functions) 참조). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** 텍스트가 조건을 충족하면 `1`, 그렇지 않으면 `0`을 반환합니다. 요청이 실패하고 `ai_function_throw_on_error`가 비활성화된 경우 기본값(`0`)을 반환합니다. [`UInt8`](/ko/reference/data-types/int-uint) **예시** **부정적인 리뷰 필터링** ```sql title=Query theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping') ``` **명시적으로 제공한 자격 증명으로 컬럼 필터링** ```sql title=Query theme={null} SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues 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.` **구문** ```sql theme={null} aiGenerate(prompt[, params]) ``` **별칭**: `AIGenerate` **인수** * `prompt` — 모델에 보낼 사용자 프롬프트 또는 질문입니다. [`String`](/ko/reference/data-types/string) * `params` — 선택적 상수 `Map(String, String)` 매개변수 맵입니다. 함수별 키는 다음과 같습니다: `temperature` (무작위성을 제어하는 샘플링 온도, 기본값 `0.7`), `max_tokens` (호출당 최대 출력 토큰 수, 기본값 `1024`), `system_prompt` (모델 동작을 안내하는 상수 시스템 수준 지침, 기본값은 일반적인 어시스턴트 프롬프트). 공통 매개변수인 `credentials`와 `model`도 적용됩니다([AI 함수](/ko/reference/functions/regular-functions/ai-functions) 참조). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** 생성된 텍스트 응답 또는 요청이 실패하고 `ai_function_throw_on_error`가 비활성화된 경우 컬럼 타입의 기본값(빈 문자열)입니다. [`String`](/ko/reference/data-types/string) **예시** **간단한 질문** ```sql title=Query theme={null} SELECT aiGenerate('What is 2 + 2? Reply with just the number.') ``` ```response title=Response theme={null} 4 ``` **명시적 자격 증명과 시스템 프롬프트 사용** ```sql title=Query theme={null} SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.')) ``` **컬럼 값 요약** ```sql title=Query theme={null} SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5 ```
## aiRedact
도입 버전: v26.8.0 LLM 프로바이더를 사용하여 지정된 텍스트에서 개인 식별 정보(PII)를 감지하고 마스킹합니다. `aiRedact`는 LLM을 사용해 최선의 노력으로 PII를 감지하고 마스킹하므로, 출력 결과를 신뢰할 수 없습니다. PII의 감지 및 제거 여부는 선택한 모델, 프롬프트, 입력에 따라 달라집니다. 모델은 식별자를 놓치거나 일부만 마스킹하거나 주변 텍스트를 변경할 수 있습니다. 형식이 잘 갖춰진 영어 텍스트에서 가장 잘 작동하며, 다른 언어 또는 철자, 문장 부호, 문법 오류가 많은 텍스트에서는 결과가 더 나쁠 수 있습니다. `aiRedact`는 출력에 PII가 없음을 보장하지 않으며, 그 자체로 안전하거나 충분한 익명화 수단으로 간주해서는 안 됩니다. 신뢰할 수 없는 당사자에게 데이터를 노출하기 전에 항상 출력을 검토하여 조직의 데이터 개인정보 보호 및 컴플라이언스 정책을 충족하는지 확인하십시오. 감지된 각 PII 스팬은 마스킹 토큰(기본값은 `[REDACTED]`이며, `replacement` 매개변수로 구성 가능)으로 대체됩니다. `categories` 배열은 마스킹할 PII 유형을 제한하며, 빈 배열을 지정하면 일반적인 카테고리(이름, 이메일, 전화번호, 주소, 신용카드, IP 주소)의 기본 세트가 사용됩니다. `aiRedact`는 모델에 감지된 PII 스팬만 변경하도록 지시하지만, 주변 텍스트 보존은 최선의 노력으로만 이루어지므로 모델이 여전히 이를 변경할 수 있습니다(위 경고 참고). 탭, 줄바꿈, 캐리지 리턴 이외의 제어 문자는 요청 전에 공백으로 정규화되므로, 이러한 문자가 포함된 입력의 경우 출력은 입력과 바이트 단위로 동일하지 않습니다. `aiRedact`는 PII가 대체된 전체 입력 텍스트를 반환하므로 출력 길이는 입력과 거의 같습니다. `max_tokens`(기본값 `1024`)는 입력의 토큰 길이보다 크게 설정하십시오. 제한값이 너무 낮아 응답이 잘리면 불완전해집니다. **구문** ```sql theme={null} aiRedact(text, categories[, params]) ``` **별칭**: `AIRedact` **인수** * `text` — 마스킹할 텍스트입니다. [`String`](/ko/reference/data-types/string) * `categories` — 마스킹할 PII 카테고리의 상수 목록입니다(예: `['name', 'ssn', 'credit_card']`). 빈 배열을 지정하면 일반적인 카테고리(이름, 이메일, 전화번호, 주소, 신용카드, IP 주소)의 기본 집합이 사용됩니다. [`Array(String)`](/ko/reference/data-types/array) * `params` — 선택적 상수 `Map(String, String)` 매개변수입니다. 함수별 키는 다음과 같습니다. `temperature`(무작위성을 제어하는 샘플링 온도, 기본값 `0.0`), `max_tokens`(호출당 최대 출력 토큰 수, 기본값 `1024` — `aiRedact`는 전체 텍스트를 반환하므로 입력 토큰 수보다 크게 설정해야 합니다. 그렇지 않으면 응답이 잘리거나 불완전할 수 있습니다), `replacement`(감지된 각 PII 스팬을 대체할 토큰, 기본값 `[REDACTED]`). 공통 매개변수인 `credentials` 및 `model`도 적용됩니다([AI 함수](/ko/reference/functions/regular-functions/ai-functions) 참조). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** 감지된 PII를 마스킹 토큰으로 대체한 텍스트입니다. 요청에 실패하고 `ai_function_throw_on_error`가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. [`String`](/ko/reference/data-types/string) **예시** **특정 카테고리 마스킹** ```sql title=Query theme={null} SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name']) ``` ```response title=Response theme={null} Purchase was done by customer [REDACTED] with email [REDACTED] ``` **사용자 지정 토큰으로 기본 PII 카테고리를 마스킹합니다** ```sql title=Query theme={null} SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5 ```
## aiSimilarity
도입 버전: v26.8.0 구성된 임베딩 제공자를 사용하여 두 텍스트의 의미적 유사도를 계산합니다. 두 텍스트의 벡터 임베딩을 계산하고 [코사인 유사도](https://en.wikipedia.org/wiki/Cosine_similarity)를 반환합니다. 점수 `-1`은 서로 반대 방향을 가리키는 임베딩 벡터에 해당하며, 의미적으로 점수가 `-1`에 가까운 텍스트는 의미가 반대임을 뜻합니다. 점수 `0`은 벡터가 직교함을 의미하며, 의미적으로 서로 관련이 없습니다. 마지막으로 점수 `1`은 임베딩 벡터가 같은 방향을 가리킴을 의미하며, 점수가 `1`에 가까운 텍스트는 의미가 유사합니다. 이는 동일한 임베딩에 대한 `cosineDistance`의 보수입니다 (`aiSimilarity = 1 - cosineDistance(embedding1, embedding2)`). 배칭, 자격 증명 및 `dimensions` 매개변수는 `ai_function_embedding_default_credentials` 기본 자격 증명 설정을 포함하여 `aiEmbed`와 동일합니다. `aiEmbed`와 마찬가지로 `model`은 명명된 컬렉션이나 매개변수 맵에서 읽어 오지 않는 필수 위치 인수(상수 `String`)입니다. **구문** ```sql theme={null} aiSimilarity(text1, text2, model[, params]) ``` **별칭**: `AISimilarity` **인수** * `text1` — 첫 번째 텍스트입니다. [`String`](/ko/reference/data-types/string) * `text2` — 두 번째 텍스트입니다. [`String`](/ko/reference/data-types/string) * `model` — 임베딩 모델 이름입니다. [`const String`](/ko/reference/data-types/string) * `params` — 선택적 상수 `Map(String, String)` 매개변수입니다. 함수별 키는 `dimensions`입니다(임베딩의 대상 차원 수이며, `0` 또는 생략 시 모델의 네이티브 크기를 사용합니다). 공통 매개변수 `credentials`도 적용됩니다([AI 함수](/ko/reference/functions/regular-functions/ai-functions) 참조). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** `[-1, 1]` 범위의 코사인 유사도입니다. 두 텍스트 중 하나가 NULL이거나 비어 있는 경우, 임베딩 요청이 실패했고 `ai_function_throw_on_error`가 비활성화된 경우 또는 QUOTA를 초과했고 `ai_function_throw_on_quota_exceeded`가 비활성화된 경우에는 NULL을 반환합니다. [`Nullable(Float32)`](/ko/reference/data-types/nullable) **예시** **두 문자열 비교(`ai_function_embedding_default_credentials` 설정이 지정되어 있으면 `credentials`를 생략할 수 있음)** ```sql title=Query theme={null} SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **쿼리와의 유사도에 따라 리뷰 순위 지정** ```sql title=Query theme={null} SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100 ``` **self-join을 통한 의미 기반 중복 제거** ```sql title=Query theme={null} SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9 ```
## aiTranslate
도입 버전: v26.4.0 주어진 텍스트를 LLM 프로바이더를 사용해 지정된 대상 언어로 번역합니다. 추가 스타일 또는 방언 관련 지침은 매개변수 맵의 `instructions` 키를 통해 전달할 수 있습니다(예: `'기술 용어는 번역하지 않음'`). 자격 증명(프로바이더, model, endpoint, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 `credentials` 키에서 가져오며, 맵에 해당 항목이 없으면 `ai_function_text_default_credentials` 설정에서 가져옵니다. **구문** ```sql theme={null} aiTranslate(text, target_language[, params]) ``` **별칭**: `AITranslate` **인수** * `text` — 번역할 텍스트입니다. [`String`](/ko/reference/data-types/string) * `target_language` — 대상 언어 이름 또는 BCP-47 코드입니다(예: `'French'`, `'es-MX'`). [`String`](/ko/reference/data-types/string) * `params` — 선택적 상수 `Map(String, String)` 매개변수입니다. 함수별 키는 다음과 같습니다. `temperature`(무작위성을 제어하는 샘플링 온도, 기본값 `0.3`), `max_tokens`(호출당 최대 출력 토큰 수, 기본값 `1024`), `instructions`(번역기에 대한 추가 스타일 또는 방언 지침). 공통 매개변수인 `credentials`와 `model`도 적용됩니다([AI Functions](/ko/reference/functions/regular-functions/ai-functions) 참조). [`Map(String, String)`](/ko/reference/data-types/map) **반환 값** 번역된 텍스트를 반환합니다. 요청이 실패하고 `ai_function_throw_on_error`가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. [`String`](/ko/reference/data-types/string) **예시** **프랑스어로 번역** ```sql title=Query theme={null} SELECT aiTranslate('Hello, world!', 'French') ``` ```response title=Response theme={null} Bonjour le monde! ``` **스타일 지침에 따라 일본어로 번역** ```sql title=Query theme={null} SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5 ```