Funzione ai_enrich

Si applica a: Databricks SQL Databricks Runtime

La ai_enrich() funzione genera nuove colonne per una riga da uno schema che definisci. Dato il contenuto di input e uno schema target, la funzione chiama un modello AI per riempire ogni campo. Può opzionalmente fondare i valori generati in una o più fonti di conoscenza come un indice di ricerca AI o una ricerca web in tempo reale, così i valori riflettono i tuoi dati o informazioni up-to-date piuttosto che solo i dati di addestramento del modello.

Usalo ai_enrich per aggiungere attributi derivati a una tabella su larga scala. Puoi etichettare e categorizzare i record, compilare i metadati mancanti o aggiungere contesto ricercato a ogni riga da una singola chiamata di funzione SQL. Per impostazione predefinita, ogni campo generato viene restituito con una breve spiegazione che spiega come il valore è stato derivato.

Requirements

• Databricks Runtime 18.2 o versione successiva.
• Se stai usando computazione serverless, la versione dell'ambiente serverless deve essere impostata su 3 o superiore, poiché questo abilita funzionalità come VARIANT.
• Per fondare l'arricchimento in un indice di ricerca con IA, è necessario uno o più indici di ricerca con IA da utilizzare come fonti di conoscenza.
• La ai_enrich funzione è disponibile utilizzando notebook Databricks, editor SQL, flussi di lavoro Databricks, job o pipeline dichiarative Spark su Lakeflow.

Sicurezza dei dati

I dati del documento vengono elaborati all'interno del perimetro di sicurezza di Databricks. Databricks non memorizza i parametri che vengono passati nelle chiamate di funzione AI, ma conserva i dettagli di esecuzione dei metadati, come la versione Databricks Runtime utilizzata.

Sintassi

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

Arguments

• content: espressione STRING o VARIANT . La disputa per arricchirsi. VARIANT input, come l'output di un'altra funzione AI come ai_parse_document, viene serializzato internamente in una stringa JSON.

• schema: Un STRING letterale che definisce le colonne da generare. Utilizza la stessa grammatica di ai_extract. Lo schema può essere:

  • Schema semplice: un array JSON di nomi di campi, generati come stringhe.

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

  • Schema avanzato: un oggetto JSON con informazioni di tipo, descrizioni e strutture annidate.

    • Supporta stringi tipi , integernumber, boolean, e enum . Esegue la convalida dei tipi. Massimo 500 valori di enumerazione.
    • Supporta oggetti annidati usando "type": "object" con "properties".
    • Supporta array di primitive o oggetti usando "type": "array" con "items".
    • Campo opzionale "description" per ogni proprietà per guidare il valore generato.

    {
      "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: Un optional VARIANT o STRING un'espressione contenente un array JSON di configurazioni di sorgente di conoscenza usate per mettere a terra i valori generati. Vedi Configurazione della sorgente della conoscenza.

• options: oggetto facoltativo MAP<STRING, STRING>. Tasti supportati:

  • 'version': La versione funzionale da usare.
  • 'instructions': A STRING fino a 20.000 caratteri. Guida in linguaggio naturale che descrive il compito di arricchimento. Opzionale; i nomi dei campi dello schema possono guidare l'arricchimento. Ad esempio, 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (impostazione predefinita) o 'false'. Quando 'true', ogni campo generato viene restituito come oggetto {rationale, value} , dove rationale spiega come è stato derivato il valore. Imposta solo per 'false' ritorno {value} .

Configurazione dell'origine delle informazioni

L'argomento knowledge_sources è un array JSON. Ogni elemento è un {type, description, config} inviluppo. Il type campo identifica come ai_enrich recupera il contesto di messa a terra, e contiene config la configurazione specifica per la sorgente.

Configurazione dell'indice di ricerca AI

Per un indice AI Search impostato type a vector_search, config accetta le seguenti chiavi:

Puoi configurare più di una vector_search sorgente in una singola chiamata.

Configurazione della ricerca web

Per una ricerca web impostata type a web_search, config accetta le seguenti chiavi opzionali. La ricerca web si svolge tramite la ricerca web su Azure Databricks; vedi Limitazioni per la disponibilità.

Puoi configurare al massimo una web_search fonte per chiamata.

Il seguente esempio configura un indice di ricerca AI e una ricerca web come fonti di conoscenza:

[
  {
    "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 con il seguente schema:

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

Il response campo contiene le colonne generate:

• I nomi e i tipi dei campi corrispondono alla definizione dello schema. Gli oggetti annidati e gli array mantengono la loro forma originale.
• Per impostazione predefinita (enableRationale è 'true'), ogni foglia è un {rationale, value} oggetto, dove rationale è una breve spiegazione di come è stato derivato il valore e value è il valore generato, tipizzato secondo lo schema. Quando enableRationale è 'false', ogni foglia è un {value} oggetto.
• Un value campo è null quando non può essere generato.

Il metadata campo contiene i metadati relativi alla risposta. Quando la riga è collegata a terra da una fonte di conoscenza, metadata.sources è un array degli identificatori del documento di origine che ha messo a terra la riga. Il grounding è a livello di riga, quindi sources si applica all'intera riga piuttosto che ai singoli campi.

Se content è NULL, il risultato è NULL.

Examples

Arricchimento del terreno nella ricerca web

Il seguente esempio arricchisce ogni azienda utilizzando uno schema semplice di array (ogni campo viene generato come stringa), basato su una ricerca web in tempo reale sul web aperto:

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

Limita la ricerca web a domini specifici

L'esempio seguente è lo stesso di sopra, ma limita la ricerca web a siti specifici con allowed_domains, quindi solo i risultati di quei domini fondano i valori:

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;

Applicare uno schema tipizzato con istruzioni

Il seguente esempio utilizza la stessa ricerca web aperta ma con uno schema completamente tipizzato, aggiunge instructions per orientare il compito e disabilita la logica in modo che ogni campo restituisca un valore semplice:

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;

Popola uno schema annidato

Il seguente esempio popola uno schema annidato per ogni azienda — un oggetto indirizzo strutturato, un array di nomi dei fondatori, un anno tipografizzato e un round di finanziamento annidato — basato su una ricerca web in tempo reale, così che i valori riflettano informazioni pubbliche attuali piuttosto che solo i dati di addestramento del modello:

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;

Arricchimento del terreno in un indice di ricerca AI

Il seguente esempio arricchisce ogni ticket di supporto con campi basati su un indice AI Search della documentazione prodotto, così i valori generati vengono estratti dai tuoi contenuti:

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

• Il grounding con una web_search fonte di conoscenza è disponibile solo in alcune regioni e spazi di lavoro. Vedi la ricerca web su Azure Databricks.
• L'opzione instructions è limitata a 20.000 caratteri.

Funzioni correlate

• ai_extract Funzione
• ai_search Funzione
• ai_parse_document Funzione
• ai_prep_search Funzione
• ai_query Funzione