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 defines. Dado conteúdo de entrada e um esquema alvo, a função chama um modelo de IA para preencher cada campo. Pode, opcionalmente, fundamentar os valores gerados numa ou mais fontes de conhecimento , como um índice de pesquisa por IA ou uma pesquisa web em tempo real, para que os valores reflitam os seus próprios dados ou informação up-todata, em vez dos dados de treino apenas do modelo.

Use ai_enrich para adicionar atributos derivados a uma tabela em escala. Podes etiquetar e categorizar registos, preencher metadados em falta ou anexar contexto pesquisado a cada linha a partir de uma única chamada de função SQL. Por defeito, cada campo gerado é devolvido com uma breve explicação que explica como o valor foi obtido.

Requisitos

• Databricks Runtime 18.2 ou superior.
• Se estiver a usar computação serverless, a versão do ambiente serverless deve estar definida para 3 ou superior, pois isto permite funcionalidades como VARIANT.
• Para fundamentar o enriquecimento num índice de AI Search, é necessário um ou mais índices de AI Search para usar como fontes de conhecimento.
• A ai_enrich função está disponível utilizando 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 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])

Arguments

• 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 cadeia JSON.

• schema: Um STRING literal que define as colunas a gerar. Utiliza 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ção de tipo, descrições e estruturas aninhadas.

    • Suporta string, integer, number, boolean, e enum tipos. Realiza validação de tipo. Máximo de 500 valores de enum.
    • Suporta objetos aninhados usando "type": "object" com "properties".
    • Suporta arrays de primitivos ou objetos usando "type": "array" com "items".
    • Campo opcional "description" para cada propriedade para orientar 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: Um opcional VARIANT ou STRING expressão contendo um array JSON de configurações de fonte de conhecimento usadas para aterrar os valores gerados. Ver configuração da fonte de conhecimento.

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

  • 'version': A versão da função a usar.
  • '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 gerar o enriquecimento. Por exemplo, 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (por defeito) ou 'false'. Quando 'true', cada campo gerado é devolvido como um {rationale, value} objeto, onde rationale explica como o valor foi derivado. Definir para 'false' apenas voltar.{value}

Configuração da fonte 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 contém config a configuração específica da fonte.

Configuração do índice de pesquisa por IA

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

Pode configurar mais do que uma vector_search fonte numa única chamada.

Configuração da pesquisa web

Para uma pesquisa na web com type definido para web_search, config aceita as seguintes chaves opcionais. A pesquisa web passa através da pesquisa web no Azure Databricks; veja Limitações para disponibilidade.

Pode configurar, no máximo, uma web_search fonte por chamada.

O exemplo seguinte configura um índice de pesquisa por IA e uma pesquisa 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:

• Os nomes e tipos dos campos correspondem à definição do esquema. Objetos aninhados e matrizes mantêm a sua forma original.
• Por defeito (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 não pode ser gerado.

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

Se content for igual a NULL, o resultado é NULL.

Examples

Enriquecimento do solo na pesquisa web

O exemplo seguinte enriquece cada empresa usando um esquema simples de array (cada campo é gerado como uma cadeia), baseado numa pesquisa web em tempo real através da 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 pesquisa web a domínios específicos

O exemplo seguinte é o mesmo acima, mas restringe a pesquisa web a sites específicos com allowed_domains, pelo que 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 seguinte usa a mesma pesquisa web aberta mas com um esquema completo e tipado, acrescenta instructions para orientar a tarefa e desativa a justificação para que cada campo devolva 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;

Preenche um esquema aninhado

O exemplo seguinte preenche um esquema aninhado para cada empresa — um objeto de endereço estruturado, um array de nomes de fundadores, um ano digitado e uma ronda de financiamento aninhada — baseado numa pesquisa web em tempo real, de modo que os valores reflitam informação pública atual e não apenas os dados de treino 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 do solo num índice de pesquisa por IA

O exemplo seguinte enriquece cada ticket de suporte com campos baseados num índice de pesquisa por IA da documentação do produto, de modo que os valores gerados são retirados 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 espaços de trabalho. Veja a pesquisa web no Azure Databricks.
• A instructions opção está 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