> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ai_function_* 세션 설정

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

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>베타</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>베타 기능</span>
        </a>;
};

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["버전", "기본값", "설명"];
  const border = "1px solid rgba(128, 128, 128, 0.3)";
  const cell = {
    border,
    padding: "0.25rem 0.5rem",
    textAlign: "start",
    verticalAlign: "top"
  };
  return <details className="not-prose" style={{
    border,
    borderRadius: "0.5rem",
    margin: "0.5rem 0",
    padding: "0.5rem 0.75rem",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <summary style={{
    cursor: "pointer",
    fontWeight: 600,
    opacity: 0.72
  }}>
        버전 이력
      </summary>
      <table style={{
    borderCollapse: "collapse",
    width: "100%",
    margin: "0.5rem 0 0"
  }}>
        <thead>
          <tr>
            {headers.map(header => <th key={header} style={{
    ...cell,
    fontWeight: 600,
    opacity: 0.72
  }}>
                {header}
              </th>)}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, row_index) => <tr key={row.id ?? row_index}>
              {(row.items ?? []).map((item, item_index) => <td key={item_index} style={{
    ...cell,
    overflowWrap: "anywhere"
  }}>
                  {item?.label}
                </td>)}
            </tr>)}
        </tbody>
      </table>
    </details>;
};

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>;
};

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

## ai\_function\_allow\_insecure\_endpoint

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "0"},{"label": "AI 함수는 이제 기본적으로 원격 호스트의 안전하지 않은(http) 엔드포인트를 거부합니다."}]}]} />

false(기본값)로 설정하면 AI 함수는 프롬프트와 API Key를 암호화되지 않은 연결로 원격 호스트에 전송하는 명명된 컬렉션 `endpoint` 사용을 거부합니다. 루프백이 아닌 호스트를 사용하는 HTTPS 이외의 모든 엔드포인트는 예외와 함께 거부됩니다. 루프백 엔드포인트(예: 로컬 `http://localhost` 모델 서버)는 항상 허용됩니다. 원격 호스트에서 평문 `http://` 엔드포인트를 허용하려면 true로 설정하십시오.

## ai\_function\_embedding\_default\_credentials

<BetaBadge />

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

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

## ai\_function\_embedding\_max\_batch\_size

<BetaBadge />

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

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

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

## ai\_function\_max\_api\_calls\_per\_query

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "1000"},{"label": "기본적으로 쿼리당 외부로 전송되는 AI 함수 HTTP 호출 수를 제한합니다(이전에는 0, 즉 무제한)."}]}, {"id": "row-2","items": [{"label": "26.4"},{"label": "0"},{"label": "새로운 설정"}]}]} />

AI 함수가 쿼리당 전송할 수 있는 HTTP 요청의 최대 개수입니다. 각 서버와 쿼리 프래그먼트에서 독립적으로 적용됩니다. 하나의 실행 Context 내에서는 해당 Context의 모든 AI 함수, 블록, 스레드가 공유하는 정확한 상한이지만, 분산 쿼리는 세그먼트 또는 병렬 레플리카 프래그먼트당 최대 이만큼의 요청을 전송할 수 있습니다. 최상위 쿼리에서 설정해야 하며, 하위 쿼리의 `SETTINGS` 재정의는 무시됩니다. 비활성화하려면 0으로 설정합니다.

## ai\_function\_max\_input\_tokens\_per\_query

<BetaBadge />

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

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

단일 쿼리에서 모든 AI 함수 API 호출에 걸친 입력(프롬프트) 토큰의 최대 총수입니다. 이 값은 프로바이더 응답을 기준으로 누적 추적됩니다. 호출의 입력 토큰 수는 응답이 도착할 때까지 알 수 없으므로, 이 제한은 진행 중인 요청마다 한 번의 호출에 해당하는 입력 토큰 수만큼 초과될 수 있습니다. 다른 AI QUOTA와 마찬가지로 이 제한은 분산 쿼리 전체에서 합산되지 않고 서버/쿼리 프래그먼트별로 적용되며, 최상위 쿼리에서 설정해야 합니다. 하위 쿼리의 `SETTINGS` 재정의는 무시됩니다. 비활성화하려면 0으로 설정하십시오.

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

## ai\_function\_max\_output\_tokens\_per\_query

<BetaBadge />

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

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

단일 쿼리에서 수행되는 모든 AI 함수 API 호출에 대해, 전체 출력(completion) 토큰의 총합으로 허용되는 최대값입니다. 이 값은 프로바이더의 응답을 기준으로 누적 추적됩니다. 호출의 출력 토큰 수는 응답이 도착해야 알 수 있으므로, 진행 중인 요청마다 한 번의 호출에서 생성된 출력 토큰 수만큼 이 제한을 초과할 수 있습니다. 다른 AI QUOTA와 마찬가지로 이 제한은 분산 쿼리 전체에서 합산되지 않고 서버 / 쿼리 프래그먼트별로 적용되며, 최상위 쿼리에서 설정해야 합니다. 하위 쿼리의 `SETTINGS` 재정의는 무시됩니다. 비활성화하려면 0으로 설정하십시오.

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

## ai\_function\_max\_retries

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.9"},{"label": "1"},{"label": "기본적으로 일시적 API 오류는 한 번 재시도하므로 프로바이더에서 단일 429 또는 5xx가 발생해도 쿼리가 실패하지 않습니다."}]}, {"id": "row-2","items": [{"label": "26.4"},{"label": "0"},{"label": "새로운 설정"}]}]} />

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

## ai\_function\_request\_timeout\_sec

<BetaBadge />

<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`에 따라 재시도될 수 있습니다.

## ai\_function\_retry\_initial\_delay\_ms

<BetaBadge />

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

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

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

## ai\_function\_text\_default\_credentials

<BetaBadge />

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

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

## ai\_function\_throw\_on\_error

<BetaBadge />

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

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

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

## ai\_function\_throw\_on\_quota\_exceeded

<BetaBadge />

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

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

true이면(기본값) AI 함수 QUOTA 한도(`ai_function_max_input_tokens_per_query`, `ai_function_max_output_tokens_per_query`, 또는 `ai_function_max_api_calls_per_query`)를 초과할 때 예외를 발생시키고 쿼리를 중단합니다. false이면 나머지 행에는 컬럼 타입의 기본값이 적용됩니다(`String`은 빈 문자열). QUOTA 한도와 마찬가지로 이는 최상위 쿼리에서 설정해야 하며, 하위 쿼리의 `SETTINGS` 재정의는 무시됩니다.