ai_enrich functie

Van toepassing op: Databricks SQL Databricks Runtime

De ai_enrich() functie genereert nieuwe kolommen voor een rij uit een schema dat je definieert. Gegeven invoerinhoud en een doelschema roept de functie een AI-model aan om elk veld in te vullen. Het kan optioneel de gegenereerde waarden verankeren in een of meer kennisbronnen , zoals een AI Search index of een live webzoekopdracht, zodat de waarden je eigen data of up-to-datum informatie weerspiegelen in plaats van alleen de trainingsdata van het model.

Gebruik ai_enrich om afgeleide attributen op schaal aan een tabel toe te voegen. Je kunt records taggen en categoriseren, ontbrekende metadata invullen, of onderzochte context koppelen aan elke rij vanuit één SQL-functieaanroep. Standaard wordt elk gegenereerd veld teruggegeven met een korte rationale die uitlegt hoe de waarde is afgeleid.

Requirements

• Databricks Runtime 18.2 of hoger.
• Als je Serverless compute gebruikt, moet de serverless omgevingsversie op 3 of hoger worden gezet, omdat dit functies zoals VARIANTmogelijk maakt.
• Om verrijking in een AI Search index te verankeren, heb je één of meer AI Search indexen nodig om als kennisbronnen te gebruiken.
• De ai_enrich functie is beschikbaar via Databricks-notebooks, SQL-editor, Databricks-workflows, jobs of Spark Declarative Pipelines op Lakeflow.

Gegevensbeveiliging

Uw documentgegevens worden verwerkt binnen de Databricks-beveiligingsperimeter. Databricks slaat de parameters die aan de AI-functieaanroepen worden doorgegeven niet op, maar behoudt wel details van de uitvoering van metadata, zoals de gebruikte Databricks Runtime-versie.

Syntaxis

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

Arguments

• content: Een STRING- of VARIANT-expressie. De rij om te verrijken. VARIANT input, zoals de output van een andere AI-functie zoals ai_parse_document, wordt intern geserialiseerd naar een JSON-string.

• schema: Een STRING letterlijke die de kolommen definieert die gegenereerd moeten worden. Het gebruikt dezelfde grammatica als ai_extract. Het schema kan het volgende zijn:

  • Eenvoudig schema: Een JSON-array van veldnamen, die als strings worden gegenereerd.

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

  • Geavanceerd schema: Een JSON-object met type-informatie, beschrijvingen en geneste structuren.

    • Ondersteunt string, integer, , numberen booleanenum typen. Voert typevalidatie uit. Maximum van 500 enumwaarden.
    • Ondersteunt geneste objecten met behulp van "type": "object" ."properties"
    • Ondersteunt arrays van primitieven of objecten die met "type": "array" ."items"
    • Optioneel "description" veld voor elke eigenschap om de gegenereerde waarde te sturen.

    {
      "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: Een optionele VARIANT of STRING expressie met een JSON-array van kennisbronconfiguraties die worden gebruikt om de gegenereerde waarden te aarden. Zie Knowledge source configuratie.

• options: Een optioneel MAP<STRING, STRING>. Ondersteunde sleutels:

  • 'version': De functieversie die gebruikt moet worden.
  • 'instructions': A STRING van maximaal 20.000 tekens. Natuurlijke taalgids die de verrijkingstaak beschrijft. Optioneel; alleen de schemaveldnamen kunnen de verrijking aansturen. Bijvoorbeeld: 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (standaard) of 'false'. Wanneer 'true', wordt elk gegenereerd veld als object {rationale, value} teruggegeven, waarbij rationale wordt uitgelegd hoe de waarde is afgeleid. Zet op 'false' alleen retourneren {value} .

Configuratie van kennisbron

Het knowledge_sources argument is een JSON-array. Elk element is een {type, description, config} envelop. Het type veld identificeert hoe ai_enrich aardingscontext wordt opgehaald, en het config veld bevat de bronspecifieke configuratie.

AI Search indexconfiguratie

Voor een AI-zoekindex met type ingesteld op vector_searchaccepteert de config volgende sleutels:

Je kunt meer dan één vector_search bron configureren in één aanroep.

Webzoekconfiguratie

Voor een webzoekopdracht met type ingesteld op web_searchaccepteert de config volgende optionele sleutels. Webzoekopdracht loopt via webzoekopdracht op Azure Databricks; zie Beperkingen voor beschikbaarheid.

Je kunt maximaal één web_search bron per oproep configureren.

Het volgende voorbeeld configureert een AI-zoekindex en een webzoekopdracht als kennisbronnen:

[
  {
    "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 met het volgende 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.
}

Het response veld bevat de gegenereerde kolommen:

• Veldnamen en -typen komen overeen met de schemadefinitie. Geneste objecten en arrays behouden hun oorspronkelijke vorm.
• Standaard (enableRationale is 'true'), is elk blad een {rationale, value} object, waarbij rationale een korte uitleg is van hoe de waarde is afgeleid en value de gegenereerde waarde is, getypt volgens het schema. Wanneer enableRationale is 'false', is elk blad een {value} object.
• Een veld is valuenull wanneer het niet gegenereerd kan worden.

Het metadata veld bevat metagegevens over het antwoord. Wanneer de rij geaard is door een kennisbron, metadata.sources is er een array van de brondocumentidentificaties die de rij hebben geaard. Aarding is op rijniveau, dus sources geldt voor de hele rij in plaats van voor individuele velden.

Als contentNULL is, dan is het resultaat NULL.

Examples

Basisverrijking

Het volgende voorbeeld genereert twee kolommen voor elke bedrijfsnaam op basis van de eigen kennis van het model. Omdat rationale standaard aan staat, wordt elk veld als object {rationale, value} teruggegeven:

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

Gestructureerd schema met instructies

Het volgende voorbeeld definieert een getypeerd schema, voegt toe instructions om de taak te sturen, en schakelt de rationale uit zodat elk veld een gewone waarde teruggeeft:

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;

Genereer een genest schema

Het volgende voorbeeld genereert een genest schema voor elk bedrijf — een gestructureerd adresobject, een array van oprichtersnamen, een getypt jaar en een geneste financieringsronde:

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;

Grondverrijking in een AI-zoekindex

Het volgende voorbeeld verrijkt elk supportticket met velden die gebaseerd zijn op een AI-zoekindex van productdocumentatie, zodat de gegenereerde waarden uit je eigen inhoud worden gehaald:

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;

Grondverrijking met webzoekopdrachten

Het volgende voorbeeld verrijkt elke bedrijfsrij met up-to-datuminformatie die van het web is opgehaald:

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

• Gronden met een web_search kennisbron is alleen beschikbaar in sommige regio's en werkruimtes. Zie webzoekopdracht op Azure Databricks.
• De instructions optie is beperkt tot 20.000 tekens.

Gerelateerde functies

• ai_extract Functie
• ai_search Functie
• ai_parse_document Functie
• ai_prep_search Functie
• ai_query Functie