Funzione ai_enrich

Si applica a: Databricks SQL Databricks Runtime

Importante

Questa funzionalità è in versione beta. Gli amministratori dell'area di lavoro possono controllare l'accesso a questa funzionalità dalla pagina Anteprime . Vedere Gestire le anteprime di Azure Databricks.

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.

Key	Obbligatorio	Descrizione
type	Sì	Il tipo di fonte di conoscenza. Uno di vector_search (un indice di ricerca IA) oppure web_search.
description	No	Una descrizione in linguaggio naturale della fonte. Usata per aiutare la funzione a decidere quando e come recuperare da esso.
config	Sì	Un oggetto contenente la configurazione specifica della sorgente. Vedi configurazione dell'indice AI Search per vector_search e configurazione di ricerca web per web_search.

Configurazione dell'indice di ricerca AI

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

Key	Obbligatorio	Descrizione
index_name	Sì	Il nome a tre livelli del Catalogo Unity dell'indice AI Search, ad catalog.schema.my_indexesempio .
text_col	Sì	La colonna nell'indice che contiene il testo del documento.
doc_uri_col	Sì	La colonna nell'indice che contiene l'URI del documento.
filter_columns	No	Una stringa separata da virgole o un array JSON di colonne disponibili per il filtraggio dei metadati. Quando omessi, la lista deriva dallo schema indicizzato, escludendo le colonne riservate, testuali e URI del documento.

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à.

Key	Obbligatorio	Descrizione
allowed_domains	No	Un array JSON di domini a cui limitare la ricerca. Quando impostato, vengono utilizzati solo i risultati di questi domini.
blocked_domains	No	Un array JSON di domini da escludere dalla ricerca.

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 di base

Il seguente esempio genera due colonne per ciascun nome aziendale utilizzando le conoscenze personali del modello. Poiché la razionalizzazione è attivata di default, ogni campo viene restituito come oggetto {rationale, value} :

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

Schema strutturato con istruzioni

Il seguente esempio definisce uno schema tipizzato, aggiunge instructions elementi per orientare il compito e disabilita la razionalità affinché ogni campo restituisca un valore semplice:

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;

Genera uno schema annidato

Il seguente esempio genera uno schema annidato per ogni azienda — un oggetto di indirizzo strutturato, un array di nomi fondatori, un anno tipizzato e un round di finanziamento annidato:

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;

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;

Arricchimento del terreno con ricerca web

Il seguente esempio arricchisce ogni riga aziendale con informazioni up-todata recuperate dal web:

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

• 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