> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ai_function_* 세션 설정

> ai_function_* 생성 그룹에 속한 ClickHouse 세션 설정입니다.

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>유형</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>기본값</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          재시작 없이 변경 가능
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            실험 기능입니다. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">자세히 알아보세요.</a></u>
        </div>;
};

이러한 설정은 [system.settings](/docs/ko/reference/system-tables/settings)에서 확인할 수 있으며, [소스 코드](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp)로부터 자동 생성됩니다.

<div id="ai_function_embedding_default_credentials">
  ## ai\_function\_embedding\_default\_credentials
</div>

<ExperimentalBadge />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": ""},{"label": "새로운 설정"}]}]} />

호출에서 매개변수 맵으로 `credentials`를 전달하지 않을 때 `aiEmbed`가 사용하는 명명된 컬렉션의 이름입니다. 비어 있으면 기본값이 없다는 뜻이며, 이런 호출에서는 `credentials`를 명시적으로 전달해야 합니다. `aiEmbed`는 `model`을 필수 위치 인수로 받으며, 명명된 컬렉션에서 가져오지 않습니다. 임베딩 엔드포인트는 채팅 엔드포인트와 다르므로 `ai_function_text_default_credentials`와는 별도로 유지됩니다.

<div id="ai_function_embedding_max_batch_size">
  ## ai\_function\_embedding\_max\_batch\_size
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="NonZeroUInt64" default_value="100" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.6"},{"label": "100"},{"label": "새로운 설정"}]}]} />

`aiEmbed`가 수행하는 단일 HTTP 요청에 포함할 수 있는 최대 텍스트 수입니다. API 호출 오버헤드를 줄이기 위해 텍스트는 이 크기의 배치로 묶입니다. 예를 들어 서로 다른 텍스트 500개와 배치 크기 100을 사용하면 HTTP 요청이 5회 발생합니다.

<div id="ai_function_max_api_calls_per_query">
  ## ai\_function\_max\_api\_calls\_per\_query
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "0"},{"label": "새로운 설정"}]}]} />

AI 함수가 쿼리당 전송할 수 있는 HTTP 요청의 최대 개수입니다. 비활성화하려면 0으로 설정합니다.

<div id="ai_function_max_input_tokens_per_query">
  ## ai\_function\_max\_input\_tokens\_per\_query
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="1000000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1000000"},{"label": "새로운 설정"}]}]} />

단일 쿼리에서 모든 AI 함수 API 호출에 걸친 입력(프롬프트) 토큰의 최대 총수입니다. 이 값은 provider 응답을 기준으로 누적 추적됩니다. 호출의 입력 토큰 수는 사전에 알 수 없으므로, 이 제한은 한 번의 호출에 해당하는 입력 토큰 수만큼 초과될 수 있습니다. 비활성화하려면 0으로 설정하십시오.

이 제한은 응답에 `usage` 객체를 포함해 보고하는 provider(OpenAI, Anthropic, vLLM)에만 적용됩니다. 토큰 사용량을 생략하는 provider(특히 HuggingFace TEI)의 경우 카운터가 0으로 유지되므로, 이러한 호출 수를 제한하려면 대신 `ai_function_max_api_calls_per_query`를 사용하십시오.

<div id="ai_function_max_output_tokens_per_query">
  ## ai\_function\_max\_output\_tokens\_per\_query
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="500000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "500000"},{"label": "새로운 설정"}]}]} />

단일 쿼리에서 수행되는 모든 AI 함수 API 호출에 대해, 전체 출력(completion) 토큰의 총합으로 허용되는 최대값입니다. 이 값은 provider의 응답을 기준으로 누적 추적됩니다. 호출의 출력 토큰 수는 사전에 알 수 없으므로, 이 제한은 한 번의 호출에서 생성된 출력 토큰 수만큼 초과될 수 있습니다. 비활성화하려면 0으로 설정하십시오.

이 제한은 응답에 `usage` 객체를 포함해 보고하는 provider(OpenAI, Anthropic, vLLM)에만 적용됩니다. 임베딩 함수(특히 aiEmbed)에는 적용되지 않으며, 이러한 함수는 출력 토큰을 생성하지 않습니다.

<div id="ai_function_max_retries">
  ## ai\_function\_max\_retries
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "0"},{"label": "새로운 설정"}]}]} />

개별 API 요청에서 일시적 오류가 발생했을 때의 최대 재시도 횟수입니다. 각 재시도에는 `ai_function_retry_initial_delay_ms`에서 시작하는 지수 백오프가 적용됩니다.

<div id="ai_function_request_timeout_sec">
  ## ai\_function\_request\_timeout\_sec
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="60" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "60"},{"label": "새로운 설정"}]}]} />

AI 함수가 수행하는 개별 HTTP 요청(AI chat completions 및 임베딩 API 호출)의 시간 제한(초)입니다. 요청이 이 시간 내에 완료되지 않으면 실패한 것으로 처리되며, `ai_function_max_retries`에 따라 재시도될 수 있습니다.

<div id="ai_function_retry_initial_delay_ms">
  ## ai\_function\_retry\_initial\_delay\_ms
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="1000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1000"},{"label": "새로운 설정"}]}]} />

실패한 AI 함수 API 요청을 처음 재시도하기 전의 초기 지연 시간이며, 단위는 밀리초입니다. 이후 각 시도에서는 지연 시간이 2배씩 증가합니다(지수 백오프). 예를 들어 기본 설정에서는 1000ms, 2000ms, 4000ms입니다.

<div id="ai_function_text_default_credentials">
  ## ai\_function\_text\_default\_credentials
</div>

<ExperimentalBadge />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": ""},{"label": "새로운 설정"}]}]} />

텍스트 AI 함수(`aiGenerate`, `aiClassify`, `aiExtract`, `aiTranslate`) 호출에서 매개변수 맵에 `credentials`가 전달되지 않은 경우 사용되는 명명된 컬렉션의 이름입니다. 비어 있으면 기본값이 없다는 뜻이며, 이러한 호출에서는 `credentials`를 명시적으로 전달해야 합니다. chat-completions 엔드포인트는 임베딩s 엔드포인트와 다르므로, 이 설정은 `ai_function_embedding_default_credentials`와는 별개입니다.

<div id="ai_function_throw_on_error">
  ## ai\_function\_throw\_on\_error
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1"},{"label": "새로운 설정"}]}]} />

true(기본값)이면 모든 재시도를 소진한 후에도 영구적으로 실패한 AI 함수 호출이 예외를 발생시키며 쿼리를 중단합니다. false이면 실패한 행에는 컬럼 타입의 기본값이 적용되며(String의 경우 빈 문자열), 처리는 계속됩니다.

<div id="ai_function_throw_on_quota_exceeded">
  ## ai\_function\_throw\_on\_quota\_exceeded
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1"},{"label": "새로운 설정"}]}]} />

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`은 빈 문자열).