ai_enrich Função

Aplica-se a: Databricks SQL Databricks Runtime

A ai_enrich() função gera novas colunas para uma linha a partir de um esquema que você definiu. Dado conteúdo de entrada e um esquema alvo, a função chama um modelo de IA para preencher cada campo. Ele pode, opcionalmente, fundamentar os valores gerados em uma ou mais fontes de conhecimento , como um índice de busca por IA ou uma busca web ao vivo, de modo que os valores reflitam seus próprios dados ou informações de data up-to, em vez dos dados de treinamento do modelo apenas.

Use ai_enrich para adicionar atributos derivados a uma tabela em escala. Você pode marcar e categorizar registros, preencher metadados faltantes ou anexar contexto pesquisado a cada linha a partir de uma única chamada de função SQL. Por padrão, cada campo gerado é retornado com uma breve justificativa que explica como o valor foi derivado.

Requirements

• Databricks Runtime 18.2 ou superior.
• Se você estiver usando computação serverless, a versão do ambiente serverless deve ser definida como 3 ou superior, pois isso permite recursos como VARIANT.
• Para fundamentar o enriquecimento em um índice de Busca por IA, você precisa de um ou mais índices de Busca por IA para usar como fontes de conhecimento.
• A ai_enrich função está disponível usando notebooks Databricks, editor SQL, fluxos de trabalho Databricks, jobs ou Spark Declarative Pipelines no Lakeflow.

Segurança de dados

Os dados do documento são processados dentro do perímetro de segurança do Databricks. O Databricks não armazena os parâmetros que são passados para as chamadas de função de IA, mas mantém detalhes de execução de metadados, como a versão de Runtime do Databricks utilizada.

Sintaxe

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

Argumentos

• content: uma expressão STRING ou VARIANT. A disputa para enriquecer. VARIANT a entrada, como a saída de outra função de IA como ai_parse_document, é serializada internamente para uma string JSON.

• schema: Um STRING literal que define as colunas a serem geradas. Ele usa a mesma gramática que ai_extract. O esquema pode ser:

  • Esquema simples: Um array JSON de nomes de campos, que são gerados como strings.

    ["industry", "headquarters_country", "year_founded"]
    

  • Esquema avançado: Um objeto JSON com informações de tipo, descrições e estruturas aninhadas.

    • stringDá suporte, integer, , numbere booleanenum tipos. Executa a validação de tipo. Máximo de 500 valores de enumeração.
    • Suporta objetos aninhados usando "type": "object" com "properties".
    • Suporta arrays de primitivas ou objetos usando "type": "array" com "items".
    • Campo opcional "description" para cada propriedade para guiar o valor gerado.

    {
      "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: Uma opção VARIANT ou STRING expressão contendo um array JSON de configurações de fontes de conhecimento usadas para aterrar os valores gerados. Veja Configuração da fonte de conhecimento.

• options: um opcional MAP<STRING, STRING>. Teclas suportadas:

  • 'version': A versão da função a ser usada.
  • 'instructions': A STRING de até 20.000 caracteres. Orientação em linguagem natural que descreve a tarefa de enriquecimento. Opcional; os nomes dos campos do esquema sozinhos podem conduzir o enriquecimento. Por exemplo, 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (padrão) ou 'false'. Quando 'true', cada campo gerado é retornado como um {rationale, value} objeto, onde rationale explica como o valor foi derivado. Configure para 'false' apenas retornar {value} .

Configuração da fonte de dados de conhecimento

O knowledge_sources argumento é um array JSON. Cada elemento é um {type, description, config} envelope. O type campo identifica como ai_enrich recupera o contexto de aterramento, e o config campo contém a configuração específica da fonte.

Configuração do índice de busca da IA

Para um índice de Busca por IA com type definido para vector_search, config aceita as seguintes chaves:

Você pode configurar mais de uma vector_search fonte em uma única chamada.

Configuração de busca na web

Para uma busca na web com type definido como web_search, config aceita as seguintes chaves opcionais. A busca na web é executada pela busca na web no Azure Databricks; veja Limitações para disponibilidade.

Você pode configurar, no máximo, uma web_search fonte por chamada.

O exemplo a seguir configura um índice de busca por IA e uma busca na web como fontes de conhecimento:

[
  {
    "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 com o seguinte esquema:

{
  "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.
}

O response campo contém as colunas geradas:

• Nomes e tipos de campos correspondem à definição do esquema. Objetos aninhados e matrizes mantêm sua forma original.
• Por padrão (enableRationale é 'true'), cada folha é um {rationale, value} objeto, onde rationale é uma breve explicação de como o valor foi derivado e value é o valor gerado, tipado de acordo com o esquema. Quando enableRationale é 'false', cada folha é um {value} objeto.
• O de value um campo é null quando ele não pode ser gerado.

O metadata campo contém metadados sobre a resposta. Quando a linha é aterrada por uma fonte de conhecimento, metadata.sources é um array dos identificadores do documento fonte que aterraram a linha. O aterramento é ao nível da linha, então sources se aplica a toda a linha, e não a campos individuais.

Se content é NULL, o resultado é NULL.

Examples

Enriquecimento do solo na busca na web

O exemplo a seguir enriquece cada empresa usando um esquema simples de array (cada campo é gerado como uma string), fundamentado em uma busca web ao vivo pela web aberta:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {}
  }]')
) AS result
FROM sales.accounts.companies;

Restringa a busca na web a domínios específicos

O exemplo a seguir é o mesmo acima, mas restringe a busca na web a sites específicos com allowed_domains, então apenas os resultados desses domínios fundamentam os valores:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {"allowed_domains": ["wikipedia.org", "sec.gov"]}
  }]')
) AS result
FROM sales.accounts.companies;

Impor um esquema tipado com instruções

O exemplo a seguir usa a mesma busca aberta na web, mas com um esquema completo digitado, adiciona instructions para direcionar a tarefa e desativa a justificativa para que cada campo retorne um valor simples:

SELECT ai_enrich(
  company_name,
  '{
    "industry": {"type": "string", "description": "Primary industry"},
    "headquarters_country": {"type": "string"},
    "year_founded": {"type": "integer"}
  }',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {}
  }]'),
  options => map(
    'instructions', 'Fill each field from current, authoritative public sources. Use null when a value cannot be verified.',
    'enableRationale', 'false'
  )
) AS result
FROM sales.accounts.companies;

Preencher um esquema aninhado

O exemplo a seguir preenche um esquema aninhado para cada empresa — um objeto de endereço estruturado, um array de nomes de fundadores, um ano digitado e uma rodada de financiamento aninhada — baseado em uma busca web ao vivo para que os valores reflitam informações públicas atuais, e não apenas os dados de treinamento do modelo:

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"}
      }
    }
  }',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {}
  }]'),
  options => map('instructions', 'Ground each field in current, authoritative public sources. Use null when a value cannot be verified.')
) AS result
FROM sales.accounts.companies;

Enriquecimento de solo em um índice de busca por IA

O exemplo a seguir enriquece cada ticket de suporte com campos baseados em um índice de busca por IA da documentação do produto, de modo que os valores gerados sejam extraídos do seu próprio conteúdo:

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;

Limitations

• O grounding com uma web_search fonte de conhecimento só está disponível em algumas regiões e ambientes de trabalho. Veja a busca na web no Azure Databricks.
• A instructions opção é limitada a 20.000 caracteres.

Funções relacionadas

• ai_extract função
• ai_search função
• ai_parse_document função
• ai_prep_search função
• ai_query função