ai_enrich funkcja

Dotyczy: Databricks SQL Databricks Runtime

Funkcja ai_enrich() generuje nowe kolumny dla wiersza na podstawie schematu, który zdefiniujesz. Na podstawie treści wejściowej i docelowego schematu funkcja wywołuje model AI, który wypełnia każde pole. Może opcjonalnie opierać wygenerowane wartości na jednym lub więcej źródłach wiedzy , takich jak indeks AI Search lub narzędzie wyszukiwania na zewnętrznym serwerze Model Context Protocol (MCP), tak aby wartości odzwierciedlały Twoje własne dane lub informacje up-to-date, a nie tylko dane treningowe modelu.

Użyj ai_enrich do dodawania atrybutów pochodnych do tabeli na dużą skalę. Możesz tagować i kategoryzować rekordy, uzupełniać brakujące metadane lub przypisywać zbadany kontekst do każdego wiersza z pojedynczego wywołania funkcji SQL. Domyślnie każde wygenerowane pole zwracane jest z krótkim uzasadnieniem wyjaśniającym sposób wyprowadzenia wartości.

Wymagania

• Databricks Runtime 18.2 lub nowszy.
• Jeśli korzystasz z obliczeń serwerowych, wersja środowiska serwerless musi być ustawiona na 3 lub wyższą, ponieważ umożliwia to funkcje takie jak VARIANT.
• Aby ugruntować wzbogacenie indeksu AI Search, potrzebujesz jednego lub więcej indeksów AI Search , które będą wykorzystywane jako źródła wiedzy.
• Aby uziemić wzbogacenie na zewnętrznym serwerze MCP, potrzebujesz MCP zarejestrowanego w Unity Gateway, EXECUTE na nim oraz USE CATALOGUSE SCHEMA w katalogu nadrzędnym i schemacie. Zobacz konfigurację MCP.
• Funkcja ta ai_enrich jest dostępna za pomocą notatników Azure Databricks, edytora SQL, zadań lub potoków Lakeflow.

Bezpieczeństwo danych

Dane dokumentu są przetwarzane w ramach strefy bezpieczeństwa Databricks. Databricks nie przechowuje parametrów przekazywanych do wywołań funkcji AI, ale zachowuje szczegóły metadanych, takie jak używana wersja Databricks Runtime.

Jeśli skonfigurujesz źródło wiedzymcp, zapytanie wyszukiwania zbudowane ai_enrich z każdego wiersza jest wysyłane do zewnętrznego dostawcy, więc traktuj treść wiersza, która do niego dociera, jako dane opuszczające Azure Databricks. Zobacz konfigurację MCP.

Składnia

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

Arguments

• content: wyrażenie STRING lub VARIANT. Rząd wzbogacający ją. VARIANT wejście, takie jak wyjście innej funkcji AI, np. ai_parse_document, jest wewnętrznie serializowane do ciągu JSON.

• schema: Literal STRING , który definiuje kolumny do generowania. Używa tej samej gramatyki co ai_extract. Schemat może być:

  • Schemat prosty: tablica JSON z nazwami pól, które są generowane jako ciągi znaków.

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

  • Zaawansowany schemat: Obiekt JSON z informacjami o typie, opisami i zagnieżdżonymi strukturami.

    • Obsługuje stringtypy , , integernumber, booleani enum . Przeprowadza walidację typu. Maksymalnie 500 wartości wyliczenia.
    • Obsługuje zagnieżdżone obiekty używając "type": "object" z ."properties"
    • Obsługuje tablice prymitywów lub obiektów używając "type": "array" z ."items"
    • Opcjonalne pole dla każdej właściwości służące "description" do wyznaczania wygenerowanej wartości.

    {
      "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: Opcjonalne VARIANT wyrażenie zawierające STRING tablicę JSON konfiguracji źródeł wiedzy używanych do uziemienia wygenerowanych wartości. Zobacz Konfiguracja źródła wiedzy.

• options: opcjonalny element MAP<STRING, STRING>. Obsługiwane klucze:

  • 'version': Wersja funkcjonalna do użycia.
  • 'instructions': Do STRING 20 000 znaków. Wskazówki w języku naturalnym opisujące zadanie wzbogacające. Opcjonalnie; same nazwy pól schematu mogą napędzać wzbogacenie. Na przykład 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (wartość domyślna) lub 'false'. Gdy 'true', każde wygenerowane pole zwraca się jako {rationale, value} obiekt, gdzie rationale wyjaśnia, jak wartość została wyprowadzona. Ustaw na 'false' tylko zwrot {value} .

Konfiguracja źródła wiedzy

Argument knowledge_sources dotyczy tablicy JSON. Każdy element to koperta {type, description, config} . Pole wskazuje, type jak ai_enrich pobiera kontekst uziemienia, a pole config zawiera konfigurację specyficzną dla źródła.

Konfiguracja indeksu wyszukiwania AI

Dla indeksu wyszukiwania AI ustawionym type na , vector_searchconfig akceptuje następujące klucze:

Możesz skonfigurować więcej niż jedno vector_search źródło podczas jednego połączenia. Przykładem jest Wzbogacenie terenu w indeksie wyszukiwania AI.

Konfiguracja MCP

Źródło zakłada mcp każdy wiersz za pomocą narzędzia wyszukiwania na zewnętrznym serwerze MCP, takim jak You.com lub Exa. Użyj go do uziemienia wierszy w dostawcy wyszukiwania, u którego już masz konto. ai_enrich wywołuje narzędzie przez Unity Gateway jako tożsamość uruchamiającą zapytanie. Każde mcp źródło sumuje do pięciu URL-ów wyników do metadata.sources.

Zanim użyjesz mcp źródła:

1. Zarejestruj serwer jako MCP. Zobacz Zewnętrzne serwery MCP. Dla serwera wymienionego w Databricks Marketplace, takiego jak You.com, instalacja tej listy tworzy MCP za ciebie. Zobacz Uzyskiwanie dostępu do zewnętrznych serwerów MCP.
2. Użyj połączenia z współdzielonym poświadczeniem, takim jak klucz API dostawcy jako token nośnika. ai_enrich nie może wywołać wezwania do logowania, więc jeśli połączenie wymaga zalogowania się od każdego użytkownika, kod źródłowy mcp nie działa dla osób, które się nie zalogowały.
3. Przyznaj EXECUTE na MCP, a także USE SCHEMA na jego katalogu nadrzędnym i schemacie, USE CATALOG tożsamość wykonującą zapytanie: każdy użytkownik, czyli tożsamość run-as zadania lub potoku. Zobacz Udostępnij MCP.

Dla mcp źródła akceptuje config następujące klucze:

Dla każdego wiersza z niepustą zawartością tworzy się krótkie zapytanie wyszukiwania z zawartości wiersza, ai_enrich a następnie żądanych pól. Każde pole najwyższego poziomu dodaje swój opis lub nazwę, jeśli nie ma żadnego opisu. Zapytanie jest przycinane do max_query_chars, więc dla długiego wiersza tekst pola można odciąć. ai_enrich wywołuje narzędzie każdego mcp źródła raz za pomocą tego zapytania. Każde połączenie kończy się po 60 sekundach. Połączenie, które przeterminuje lub nie udaje się z błędem 429, 500, 502, 503 lub 504, jest powtarzane nawet trzy razy. Ponieważ powtórki mogą powtarzać połączenie, użyj narzędzia do wyszukiwania tylko do odczytu. Połączenia do dostawcy są liczone do cenowych i limitów cen Twojego konta operatora.

Jeśli wywołanie się nie powiedzie, a żadne inne źródło wiedzy nie zwraca wyników, error_message jest ustawione i response jest dla null tego wiersza. Na przykład wywołanie kończy się niepowodzeniem, jeśli dostawca odrzuci klucz API lub brak tożsamości wykonującej zapytanie EXECUTE na MCP. Jeśli inne źródło wiedzy zwraca wyniki, wiersz opiera się wyłącznie na tych wynikach i nie jest zgłaszany żaden błąd. Jeśli narzędzie nie zwraca żadnych rezultatów i żadne inne źródło wiedzy również nie zwraca, wiersz wzbogaca się wyłącznie o swoją zawartość, bez uziemienia.

Jeśli mcp źródła wiedzy nie są włączone dla przestrzeni roboczej, każdy wiersz z niepustą zawartością zwraca null dla response i , error_messagemcp knowledge source is not available: it is not enabled for this workspace.nawet gdy wywołanie konfiguruje także inne źródła wiedzy.

Możesz skonfigurować więcej niż jedno mcp źródło podczas jednego połączenia. Dla przykładu zobacz wzbogacenie naziemne w zewnętrznym dostawcy wyszukiwania MCP.

Returns

A VARIANT z następującym schematem:

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

Pole response zawiera wygenerowane kolumny:

• Nazwy i typy pól odpowiadają definicji schematu. Zagnieżdżone obiekty i tablice zachowują swój pierwotny kształt.
• Domyślnie (enableRationale jest 'true'), każdy liść jest obiektem {rationale, value} , gdzie rationale jest krótkim wyjaśnieniem sposobu wyprowadzenia tej wartości, a value jest wartością generowaną, typowaną zgodnie ze schematem. Gdy enableRationale jest , 'false'każdy liść jest obiektem {value} .
• Pole value to sytuacja, null gdy nie może być wygenerowane.

Pole metadata zawiera metadane dotyczące odpowiedzi. Gdy wiersz jest uziemiony przez źródło wiedzy, metadata.sources jest to tablica identyfikatorów dokumentów źródłowych, które uziemiły ten wiersz. Uziemienie jest na poziomie rzędów, więc sources dotyczy całego rzędu, a nie pojedynczych pól.

Jeśli content jest NULL, wynik to NULL.

Examples

Wzbogacenie podstaw w indeksie wyszukiwania AI

Poniższy przykład wzbogaca każde zgłoszenie wsparcia polami opartymi na indeksie AI Search dokumentacji produktu, tak aby wygenerowane wartości pochodziły z Twoich własnych treści:

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;

Wzbogacanie naziemne w zewnętrznym dostawcy wyszukiwania MCP

Poniższy przykład wzbogaca każdą firmę o pola oparte na You.com wynikach wyszukiwania. Narzędzie na MCP nazywa you-search się :main.default.youcom

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "mcp",
    "description": "You.com web search",
    "config": {
      "mcp_service": "main.default.youcom",
      "tool": "you-search"
    }
  }]')
) AS result
FROM sales.accounts.companies;

Poniższy przykład wykorzystuje zamiast tego Exa. Narzędzie Exa wymienia web_search_exaobjective jako wymagany argument, więc przykład przekazuje go w arguments:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "mcp",
    "description": "Exa web search",
    "config": {
      "mcp_service": "main.default.exa",
      "tool": "web_search_exa",
      "arguments": {"objective": "Find public company profile facts"}
    }
  }]')
) AS result
FROM sales.accounts.companies;

Limitations

• ai_enrich nie wspiera źródła wiedzy web_search . Aby uziemić wiersze w dostawcy wyszukiwania, użyj mcp źródła. Zobacz konfigurację MCP.
• Źródło mcp wiedzy nie może zachęcić użytkowników do zalogowania się do usługodawcy. Jeśli połączenie wymaga zalogowania się od każdego użytkownika, połączenia nie udają się dla osób, które się nie zalogowały.
• Źródło mcp wiedzy nie wspiera polityk usług , które zwracają ASK. ai_enrich Nie mogę wyświetlić wniosku o zatwierdzenie, więc połączenia wymagające zgody nie ulegają awarii.
• Opcja instructions jest ograniczona do 20 000 znaków.

Funkcje pokrewne

• ai_extract funkcja
• ai_search funkcja
• ai_parse_document funkcja
• ai_prep_search funkcja
• ai_query funkcja