`ai_enrich` 함수

적용 대상: 확인 표시 '예' Databricks SQL Databricks Runtime

Important

이 기능은 베타 버전으로 제공됩니다. 작업 영역 관리자는 미리 보기 페이지에서 이 기능에 대한 액세스를 제어할 수 있습니다. Azure Databricks 미리 보기 관리를 참조하세요.

이 함수는 ai_enrich() 당신이 정의한 스키마에서 한 행의 새로운 열을 생성합니다. 입력 콘텐츠와 타겟 스키마가 주어지면, 함수는 각 필드를 채우기 위해 AI 모델을 호출합니다. 선택적으로 생성된 값들을 AI 검색 인덱스나 라이브 웹 검색 같은 하나 이상의 지식 소스에 기반할 수 있어, 값이 모델의 학습 데이터만이 아니라 본인의 데이터나 up-to날짜 정보를 반영할 수 있습니다.

대규모로 테이블에 파생 속성을 추가하는 데 사용 ai_enrich 하세요. 레코드에 태그를 달고 분류하거나, 누락된 메타데이터를 채우거나, 단일 SQL 함수 호출로 각 행에 조사된 맥락을 첨부할 수 있습니다. 기본적으로 생성된 각 필드는 값이 어떻게 도출되었는지 설명하는 간단한 이유와 함께 반환됩니다.

Requirements

Databricks Runtime 18.2 이상.
서버리스 컴퓨트를 사용할 경우, 서버리스 환경 버전은 3 이상으로 설정해야 하며, 이는 .과 같은 VARIANT기능을 가능하게 하기 때문입니다.
AI 검색 색인에 기반을 두려면, 지식 소스로 사용할 하나 이상의 AI 검색 색인 이 필요합니다.
ai_enrich 이 기능은 Databricks 노트북, SQL 편집기, Databricks 워크플로우, 작업 또는 Lakeflow의 Spark 선언적 파이프라인을 통해 이용할 수 있습니다.

데이터 보안

문서 데이터는 Databricks 보안 경계 내에서 처리됩니다. Databricks는 AI 함수 호출에 전달되는 매개변수를 저장하지 않지만, Databricks 런타임 버전과 같은 메타데이터 실행 세부 사항은 유지합니다.

구문

ai_enrich(content, schema [, knowledge_sources] [, options])

Arguments

content: A STRING 또는 VARIANT 식입니다. 부유함을 위한 갈등. VARIANT 입력, 예를 들어 다른 AI 함수 ai_parse_document의 출력은 내부적으로 JSON 문자열로 직렬화됩니다.
schema: STRING 생성할 열을 정의하는 리터럴입니다. 이 문서는 .과 ai_extract동일한 문법을 사용합니다. 스키마는 다음과 같습니다.
- 단순 스키마: 필드 이름으로 구성된 JSON 배열로, 문자열로 생성됩니다.
```
["industry", "headquarters_country", "year_founded"]
```
- 고급 스키마: 타입 정보, 설명, 중첩된 구조를 포함하는 JSON 객체입니다.
  - , string, integernumber및 boolean 형식을 enum지원합니다. 형식 유효성 검사를 수행합니다. 최대 500개 열거형 값입니다.
  - "type": "object" "properties".
  - 를 사용하여 "type": "array""items"프리미티브 또는 객체 배열을 지원합니다.
  - 각 속성마다 생성된 값을 안내하는 선택적 "description" 필드가 있습니다.
```
{
  "hq_address": {
    "type": "object",
    "description": "Registered headquarters address",
    "properties": {
      "city": { "type": "string" },
      "country": { "type": "string" }
    }
  },
  "founding_team": { "type": "array", "description": "Full names of the founders", "items": { "type": "string" } },
  "founding_year": { "type": "integer", "description": "Year the company was founded" }
}
```
knowledge_sources: 생성된 값에 기반을 두는 지식 소스 구성의 JSON 배열을 포함하는 선택적 VARIANT 또는 STRING 표현식입니다. 지식 소스 구성(Knowledge source configuration)을 참조하세요.
options: 선택 사항 MAP<STRING, STRING>입니다. 지원되는 키:
- 'version': 사용할 기능 버전.
- 'instructions': 최대 20,000자 중 하나 STRING . 풍부화 과제를 설명하는 자연어 안내. 선택 사항입니다; 스키마 필드 이름만으로도 풍부화가 결정될 수 있습니다. 'Infer attributes for each company from its public profile.'을 예로 들 수 있습니다.
- 'enableRationale': 'true' (기본값) 또는 'false'. 이때 'true'생성된 각 필드는 객체로 {rationale, value} 반환되며, 여기서 rationale 는 값이 어떻게 도출되었는지 설명합니다. 반품 {value} 전용으로 설정 'false' 하세요.

지식 소스 구성

knowledge_sources 인자는 JSON 배열입니다. 각 요소는 하나의 봉투입니다 {type, description, config} . 필드는 type 접 ai_enrich 지 컨텍스트를 어떻게 검색하는지를 나타내며 config , 소스별 구성을 포함합니다.

Key	필수	Description
`type`	예	지식 원천 유형. (AI 검색 인덱스) 또는 `vector_searchweb_search`.
`description`	No	원천에 대한 자연어로 설명하는 것. 기능이 언제 어떻게 리브를 할지 결정하는 데 도움을 주기 위해 사용되었습니다.
`config`	예	소스별 구성을 포함하는 객체입니다. AI 검색 인덱스 구성 과 `vector_search`웹 검색 구성`web_search`를 참조하세요.

AI 검색 인덱스 구성

로 설정된 typeAI 검색 인덱스 vector_search 의 경우, config 다음 키를 수용합니다:

Key	필수	Description
`index_name`	예	예를 들어, Unity 카탈로그의 AI 검색 인덱스 3단계 명칭은 다음과 같습니다 `catalog.schema.my_index`.
`text_col`	예	문서 텍스트가 포함된 색인의 열입니다.
`doc_uri_col`	예	문서 URI가 포함된 인덱스 열입니다.
`filter_columns`	No	메타데이터 필터링에 사용할 수 있는 쉼표 구분된 문자열 또는 JSON 열 배열입니다. 누락 시 리스트는 예약, 텍스트, 문서 URI 열을 제외한 인덱스 스키마에서 파생됩니다.

한 통화에서 여러 vector_search 소스를 구성할 수 있습니다.

웹 검색 구성

웹 검색 type 에서 , 로 config 설정web_search될 때는 다음 선택적 키를 받아들입니다. 웹 검색은 Azure Databricks에서 웹 검색을 통해 실행되며; 가용성에 대한 제한 사항을 참조하세요.

Key	필수	Description
`allowed_domains`	No	검색 범위를 제한할 수 있는 JSON 도메인 배열. 설정이 가능하면 이 도메인들의 결과만 사용됩니다.
`blocked_domains`	No	검색에서 제외할 도메인의 JSON 배열입니다.

한 통화당 최대 하나의 web_search 소스만 설정할 수 있습니다.

다음 예시는 AI 검색 인덱스와 웹 검색을 지식 소스로 구성합니다:

[
  {
    "type": "vector_search",
    "description": "Internal product catalog",
    "config": {
      "index_name": "prod_catalog.docs.product_catalog",
      "text_col": "description",
      "doc_uri_col": "product_url"
    }
  },
  {
    "type": "web_search",
    "config": {
      "allowed_domains": ["wikipedia.org"]
    }
  }
]

Returns

다음과 같은 스키마를 가진 A VARIANT :

{
  "response": { ... },     // Generated columns matching the provided schema. Each leaf is returned as an object (see below).
  "error_message": null,   // null on success, or an error message on failure
  "metadata": { ... }      // Metadata about the response, including grounding sources.
}

필드는 response 생성된 열을 포함합니다:

필드 이름과 타입이 스키마 정의와 일치합니다. 중첩된 객체와 배열은 원래의 형태를 유지합니다.
기본적으로 (enableRationale 는 'true'), 각 리프는 객체이며 {rationale, value} , rationale 여기서 는 값이 어떻게 유도되었는지에 대한 간단한 설명이고, value 는 스키마에 따라 타입이 지정된 생성된 값입니다. enableRationale 가 일 때'false', 각 잎은 객체이다{value}.
필드는 value 생성할 수 없는 상태입니다 null .

필드에는 metadata 응답에 대한 메타데이터가 포함됩니다. 행이 지식 소스에 의해 접지될 때, metadata.sources 는 해당 행을 접지시킨 소스 문서 식별자 배열입니다. 접지는 행 단위로 적용되므로 sources 개별 필드가 아니라 행 전체에 적용됩니다.

content가 NULL이면 결과는 NULL입니다.

Examples

기본 농축

다음 예시는 모델 자체의 지식을 바탕으로 각 회사명에 대해 두 개의 열을 생성합니다. rationale이 기본적으로 켜져 있기 때문에 각 필드는 객체로 {rationale, value} 반환됩니다:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country"]'
) AS result
FROM sales.accounts.companies;

명령어가 있는 구조화 스키마

다음 예시는 타입이 지정된 스키마를 정의하고, instructions 작업을 조정하며, 각 필드가 평범한 값을 반환하도록 rationale을 비활성화합니다:

SELECT ai_enrich(
  review_text,
  '{
    "sentiment": {"type": "string", "description": "positive, negative, or neutral"},
    "topics": {"type": "array", "items": {"type": "string"}},
    "requires_follow_up": {"type": "boolean"}
  }',
  options => map(
    'instructions', 'Analyze the customer review and categorize it for the support team.',
    'enableRationale', 'false'
  )
) AS result
FROM support.reviews.customer_reviews;

중첩 스키마 생성

다음 예시는 각 회사별로 구조화된 주소 객체, 창업자 이름 배열, 타입된 연도, 그리고 중첩된 자금 조달 라운드를 생성합니다:

SELECT ai_enrich(
  company_name,
  '{
    "hq_address": {
      "type": "object",
      "description": "Registered headquarters address",
      "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
      }
    },
    "founding_team": {"type": "array", "description": "Full names of the founders", "items": {"type": "string"}},
    "founding_year": {"type": "integer", "description": "Year the company was founded"},
    "latest_funding_round": {
      "type": "object",
      "properties": {
        "stage": {"type": "string", "description": "Funding stage, for example Seed or Series A"},
        "amount_usd": {"type": "number", "description": "Amount raised in USD"}
      }
    }
  }'
) AS result
FROM sales.accounts.companies;

AI 검색 지수에서의 지반 농축

다음 예시는 각 지원 티켓을 제품 문서의 AI 검색 인덱스에 기반한 필드로 풍부하게 하여, 생성된 값이 여러분의 콘텐츠에서 추출되도록 합니다:

SELECT
  ticket_id,
  ai_enrich(
    customer_description,
    '{
      "affected_product": {"type": "string"},
      "suggested_resolution": {"type": "string"},
      "documentation_url": {"type": "string"}
    }',
    PARSE_JSON('[{
      "type": "vector_search",
      "description": "Product documentation and troubleshooting guides",
      "config": {
        "index_name": "support.docs.product_documentation",
        "text_col": "content",
        "doc_uri_col": "doc_url"
      }
    }]')
  ) AS result
FROM support.tickets.open_tickets;

웹 검색을 이용한 지면 농축

다음 예시는 웹에서 가져온 up-to-날짜 정보로 각 회사 행을 풍부하게 합니다:

SELECT ai_enrich(
  company_name,
  '["recent_funding_round", "latest_headline"]',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {"allowed_domains": ["reuters.com", "bloomberg.com"]}
  }]'),
  options => map('instructions', 'Find the most recent, verifiable information for each company.')
) AS result
FROM sales.accounts.companies;

Limitations

지식 소스를 이용한 web_search 접지는 일부 지역과 작업 공간에서만 가능합니다. Azure Databricks에서 웹 검색을 참고하세요.
instructions 옵션은 20,000자로 제한되어 있습니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-08-31