Funzione ai_search

Si applica a: Databricks SQL Databricks Runtime

La ai_search() funzione recupera informazioni da una o più fonti di conoscenza. Le fonti di conoscenza possono includere indici AI Search o tabelle sincronizzate Lakebase con Lakebase Search abilitato.

Data una query in linguaggio naturale e fonti di conoscenza configurate per la chiamata, la funzione genera query di ricerca ottimizzate, recupera e deduplica i risultati tra le fonti, li riclassifica per rilevanza e restituisce i documenti più rilevanti. Per impostazione predefinita, sintetizza anche una risposta in linguaggio naturale fondata sui documenti recuperati.

Utilizzarli ai_search per arricchire dati operativi con contesto rilevante su larga scala, costruire pipeline di generazione aumentata per il recupero batch (RAG) o esporre il recupero come strumento a un sistema AI composto — tutto da una singola chiamata di funzione SQL.

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.

Requirements

• Databricks Runtime 18.2 o versione successiva.
• Una o più fonti di conoscenza da ricercare: indici AI Search o tabelle sincronizzate Lakebase con Lakebase Search abilitato.
• Per usare una tabella sincronizzata Lakebase, preparatela prima per la ricerca. Vedi configurazione Lakebase.
• Se stai usando computazione serverless, la versione dell'ambiente serverless deve essere impostata su 3 o superiore, poiché questo abilita funzionalità come VARIANT.
• La ai_search funzione è disponibile utilizzando notebook Databricks, editor SQL, flussi di lavoro Databricks, job o pipeline dichiarative Spark su Lakeflow.

Sintassi

ai_search(query, knowledge_sources [, instructions] [, options])

Arguments

• query: espressione STRING o VARIANT . La query di ricerca in lingua naturale. VARIANT l'input, come l'output di un'altra funzione AI, viene serializzato internamente in una stringa JSON.
• knowledge_sources: A VARIANTSTRING o espressione contenente un array JSON di configurazioni sorgenti di conoscenza da cercare. Vedi Configurazione della sorgente della conoscenza. Puoi specificare fino a 10 fonti di conoscenza.
• instructions: Un'espressione opzionale STRING fino a 4.000 caratteri. Istruzioni in linguaggio naturale che guidano la generazione delle query, la generazione dei filtri dei metadati e la riclassificazione. Ad esempio, 'Prefer official documentation over internal articles when both cover the same topic.'
• options: oggetto facoltativo MAP<STRING, STRING>. Chiavi supportate:
  • 'version': La versione funzionale da usare.
  • 'generate_answer': 'true' (impostazione predefinita) o 'false'. Quando 'true', la funzione sintetizza una risposta in linguaggio naturale fondata dai documenti recuperati e la restituisce nel answer campo. Imposta per 'false' restituire solo i documenti.
  • 'generate_citations': 'true' oppure 'false' (predefinito). Quando 'true', la funzione restituisce citazioni che mostrano quali chunk recuperati il modello ha utilizzato per supportare la risposta generata. Questa opzione deve 'generate_answer' essere 'true'.

Configurazione dell'origine delle informazioni

L'argomento knowledge_sources è un array JSON. Ogni elemento è un {type, config} inviluppo. Il type campo identifica come ai_search si collega alla sorgente ed è separato dal nome della risorsa rivolta al cliente. Impostato type su vector_search per un indice AI Search, oppure lakebase_search per una tabella sincronizzata Lakebase con Lakebase Search abilitato. Il config campo contiene la configurazione specifica per la sorgente.

Una singola chiamata può combinarsi vector_search e lakebase_search sorgente, fino al limite di 10 sorgenti.

Configurazione dell'indice di ricerca AI

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

Il seguente esempio configura un indice di ricerca AI come fonte di conoscenza:

[
  {
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }
]

Per costruire un indice AI Search da documenti grezzi, usa ai_parse_document e ai_prep_search crea blocchi pronti per la ricerca in una tabella Delta. Poi crea un indice AI Search da quella tabella. Dopo che l'indice è online, usa il suo nome a tre livelli come index_name.

Configurazione della base del lago

Prima di poter usare una tabella sincronizzata Lakebase come fonte di conoscenza, preparatela per la ricerca:

1. Abilita Lakebase Search e installa le estensioni. Segui Lakebase Search per abilitare Lakebase Search nelle impostazioni del progetto, poi collegati al database Postgres del progetto e installa l'estensione lakebase_vector eseguendo CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;. Fornisce la ricerca vettoriale approssimativa del vicino più prossimo che ai_search utilizza. Abilitare Lakebase Search richiede l'accesso beta ed è irreversibile.
2. Sincronizza la tua tabella Unity Catalog nel progetto. Usa una tabella sincronizzata, mappa la colonna di embedding a una vector(n) colonna e costruisci un lakebase_ann indice. La dimensione n deve corrispondere all'output del tuo modello di embedding.
3. Genera gli embeddings offline con un endpoint di servizio modello. Popola la colonna di embedding con un modello di embedding — ad esempio, interrogando un modello di embedding con ai_query — poi passa lo stesso endpoint come embedding_model (vedi sotto). ai_search incorpora ogni query al momento della ricerca, così la query e gli embeddings del documento memorizzati condividono uno spazio vettoriale.

Per una sorgente di conoscenza Lakebase con type impostato a lakebase_search, config accetta le seguenti chiavi:

Il seguente esempio configura una tabella Lakebase come fonte di conoscenza. Sostituisci embedding_model con l'endpoint che hai usato per incorporare la tabella offline:

[
  {
    "type": "lakebase_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles_synced",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "embedding_column": "article_embedding",
      "embedding_model": "databricks-gte-large-en",
      "lakebase_project_id": "my-lakebase-project"
    }
  }
]

Restituzioni

A VARIANT con il seguente schema:

{
  "document": [
    {
      "page_content": STRING,  // Text content of the retrieved chunk
      "doc_uri": STRING,       // URI of the source document
      "metadata": MAP          // Additional metadata from the index
    }
  ],
  "answer": STRING,            // Grounded answer synthesized from the retrieved
                               // documents, or null
  "citations": [               // Present only when generate_citations is true
    {
      "document_index": INT    // Position in the document array above, starting at 0
    }
  ]
}

Quando generate_citations è true, leggi insieme i answer campi e citations . Ogni combinazione di valori significa qualcosa di diverso:

• Un non-null answer con un array vuoto citations significa che è stata generata una risposta, ma non è stato selezionato alcun chunk restituito.
• Un null answer con un array vuoto citations significa che la generazione delle citazioni è stata eseguita ma non ha prodotto citazioni perché non è stata generata una risposta a terra.
• Un valore nullo citations significa che la generazione di citazioni non era disponibile o non è stata invocata, incluso quando query SQL NULL.

Examples

Ricerca di base

Il seguente esempio cerca in un indice di ricerca AI e restituisce documenti classificati e una risposta fondata:

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }]')
) AS result;

Restituire i chunk di supporto per la risposta generata

Il seguente esempio restituisce il sottoinsieme dei chunk recuperati che il modello ha selezionato come supporto della risposta:

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url"
    }
  }]'),
  options => map('generate_citations', 'true')
) AS result;

L'array document contiene ancora l'intero insieme di chunk restituiti. Usa in document_index ogni citazione per selezionare quelle di supporto da quella matrice. Questi indici sono validi solo all'interno di una singola risposta. Possono cambiare tra chiamate, quando cambiano le riclassifiche o quando l'indice viene aggiornato.

Ricerca multi-sorgente con istruzioni

Il seguente esempio cerca in due indici di ricerca AI e lo utilizza instructions per guidare la generazione delle query e il riordino:

SELECT ai_search(
  'What are the networking requirements for serverless SQL warehouses?',
  PARSE_JSON('[
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.public_docs", "text_col": "content", "doc_uri_col": "doc_url"}
    },
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.internal_kb", "text_col": "body", "doc_uri_col": "source_uri"}
    }
  ]'),
  'Focus on firewall rules and VPC/VNet configuration. Prefer official documentation over internal articles when both cover the same topic.'
) AS result;

Cerca una tabella Lakebase

Il seguente esempio cerca una tabella sincronizzata su Lakebase e restituisce documenti classificati e una risposta solida:

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "lakebase_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles_synced",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "embedding_column": "article_embedding",
      "embedding_model": "databricks-gte-large-en",
      "lakebase_project_id": "my-lakebase-project"
    }
  }]')
) AS result;

Combina un indice di ricerca AI e una tabella Lakebase

Il seguente esempio cerca in un indice AI Search e in una tabella Lakebase nella stessa chiamata. I risultati di entrambe le fonti vengono deduplicati, riclassificati insieme e restituiti come un'unica lista classificata:

SELECT ai_search(
  'What are the networking requirements for serverless SQL warehouses?',
  PARSE_JSON('[
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.public_docs", "text_col": "content", "doc_uri_col": "doc_url"}
    },
    {
      "type": "lakebase_search",
      "config": {
        "index_name": "prod_catalog.docs.internal_kb_synced",
        "text_col": "body",
        "doc_uri_col": "source_uri",
        "embedding_column": "body_embedding",
        "embedding_model": "databricks-gte-large-en",
        "lakebase_project_id": "my-lakebase-project"
      }
    }
  ]')
) AS result;

Arricchisci una tabella con recupero e risposta generata

Il seguente esempio arricchisce ogni ticket di supporto con documentazione pertinente e una soluzione suggerita. Poiché la generazione delle risposte è attiva di default, la risoluzione suggerita è disponibile direttamente sul answer campo — non è necessario alcun passaggio di generazione separato.

SELECT
  ticket_id,
  customer_description,
  ai_search(
    customer_description,
    PARSE_JSON('[{
      "type": "vector_search",
      "config": {
        "index_name": "support.docs.product_documentation",
        "text_col": "content",
        "doc_uri_col": "doc_url"
      }
    }]'),
    'Find product documentation, known issues, and troubleshooting guides relevant to this support ticket.'
  ):answer::STRING AS suggested_resolution
FROM support.tickets.open_tickets;

Per controllare il formato di output o usare un modello specifico, imposta 'generate_answer' e 'false' concatena i documenti recuperati in ai_query invece.

Limitations

• ai_search supporta indici AI Search ("type": "vector_search") e tabelle sincronizzate Lakebase ("type": "lakebase_search") come fonti di conoscenza.
• Puoi specificare fino a 10 fonti di conoscenza per chiamata, in qualsiasi combinazione dei tipi supportati.
• L'argomentazione instructions è limitata a 4.000 caratteri.

Funzioni correlate

• ai_parse_document Funzione
• ai_prep_search Funzione
• ai_query Funzione
• ai_extract Funzione
• ai_enrich Funzione