SQL-Abfragen mit Fragen in natürlicher Sprache generieren

Auf dieser Seite wird beschrieben, wie Sie SQL-Anweisungen mit der AlloyDB-KI in natürlicher Sprache einrichten, konfigurieren und generieren. Mit natürlicher Sprache können Sie nutzerorientierte Anwendungen mit generativer KI erstellen, um Datenbanken in natürlicher Sprache abzufragen.

So aktivieren Sie die alloydb_ai_nl-Erweiterung, die AlloyDB for PostgreSQL Natural Language Support API:

1. Installieren Sie die alloydb_ai_nl-Erweiterung.
2. Definieren Sie eine Natural Language-Konfiguration für Ihre Anwendung.
3. Registrieren Sie ein Schema.
4. Fügen Sie Kontext hinzu.
5. Fügen Sie Abfragevorlagen hinzu.
6. Definieren Sie Konzepttypen und erstellen Sie einen Wertindex.
7. SQL-Anweisungen mithilfe einer Benutzeroberfläche für natürliche Sprache generieren

Hinweise

• Antrag auf Zugriff auf AlloyDB AI Natural Language stellen und warten, bis Sie die Aktivierungsbestätigung erhalten, bevor Sie der Anleitung auf dieser Seite folgen.
• Informationen zum Herstellen einer Verbindung zur AlloyDB-Datenbank und zum Ausführen von PostgreSQL-Befehlen Weitere Informationen finden Sie unter Verbindung – Übersicht.
• Fülle die Datenbank mit den Daten und dem Schema aus, auf die der Endnutzer zugreifen möchte.

Cluster erstellen und Vertex AI-Integration aktivieren

1. AlloyDB-Cluster und ‑Instanz erstellen Mit der AlloyDB-Instanz erstellen Sie die Anwendungsdatenbank und das Schema.
2. Aktivieren Sie die Vertex AI-Einbindung. Weitere Informationen finden Sie unter Mit Vertex AI verknüpfen.

Erforderliche Rollen

Wenn Sie die alloydb_ai_nl-Erweiterung installieren und anderen Nutzern Zugriff gewähren möchten, benötigen Sie die folgende IAM-Rolle (Identity and Access Management) im verwendeten Google Cloud-Projekt:

• roles/alloydb.admin (die vordefinierte IAM-Rolle „AlloyDB Admin“)

Weitere Informationen finden Sie unter PostgreSQL-Nutzer mit Standardauthentifizierung verwalten.

Umgebung vorbereiten

Wenn Sie Abfragen in natürlicher Sprache generieren möchten, müssen Sie die erforderliche Erweiterung installieren, eine Konfiguration erstellen und ein Schema registrieren.

Installieren Sie die Erweiterung „alloydb_nl_ai“.

Die alloydb_ai_nl-Erweiterung verwendet die google_ml_integration-Erweiterung, die mit Large Language Models (LLMs) interagiert, einschließlich Gemini-Modellen in Vertex AI.

Um die Erweiterung alloydb_ai_nl zu installieren, stellen Sie eine Verbindung zur Datenbank her und führen Sie den folgenden Befehl aus, um die Erweiterungen google_ml_integration und alloydb_ai_nl zu aktivieren.

CREATE EXTENSION google_ml_integration;
CREATE EXTENSION alloydb_ai_nl cascade;

Konfiguration in natürlicher Sprache erstellen und Schema registrieren

In AlloyDB AI Natural Language wird nl_config verwendet, um Anwendungen bestimmten Schemas, Abfragevorlagen und Modellendpunkten zuzuordnen. nl_config ist eine Konfiguration, die einer Anwendung ein Schema, Vorlagen und andere Kontexte zuordnet. Bei einer großen Anwendung können auch unterschiedliche Konfigurationen für verschiedene Teile der Anwendung verwendet werden, sofern Sie die richtige Konfiguration angeben, wenn eine Frage von diesem Teil der Anwendung gesendet wird. Sie können ein ganzes Schema oder bestimmte Schemaobjekte wie Tabellen, Ansichten und Spalten registrieren.

1. Verwenden Sie das folgende Beispiel, um eine Konfiguration für die natürliche Sprache zu erstellen:

   SELECT
     alloydb_ai_nl.g_create_configuration(
       'my_app_config'        -- configuration_id
     );
   

   „gemini-2.0-flash:generateContent“ ist der Modellendpunkt.

2. Registrieren Sie ein Schema für eine bestimmte Konfiguration mit dem folgenden Beispiel:

   SELECT
     alloydb_ai_nl.g_manage_configuration(
       operation => 'register_schema',
       configuration_id_in => 'my_app_config',
       schema_names_in => '{my_schema}'
     );
   

Kontext hinzufügen

Der Kontext umfasst alle Arten von Informationen, mit denen Sie eine Frage eines Endnutzers beantworten können. Der Kontext umfasst die Schemastruktur und ‑beziehungen, Zusammenfassungen und Beschreibungen von Spalten, Spaltenwerten und ihrer Semantik sowie Regeln oder Anweisungen der Geschäftslogik, die für die Anwendung oder Domain spezifisch sind.

Allgemeiner Kontext für anwendungsspezifische Regeln hinzufügen

Zu den allgemeinen Kontextelementen gehören anwendungsspezifische Regeln, Geschäftslogik-Anweisungen oder anwendungs- und bereichsspezifische Terminologie, die nicht mit einem bestimmten Schemaobjekt verknüpft ist.

So fügen Sie einen allgemeinen Kontext für anwendungsspezifische Regeln und anwendungs- oder domänenspezifische Terminologie hinzu:

1. Im folgenden Beispiel wird gezeigt, wie Sie ein allgemeines Kontextelement für die angegebene Konfiguration hinzufügen:

   SELECT
     alloydb_ai_nl.g_manage_configuration(
       'add_general_context',
       'my_app_config',
       general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
     );
   

   Die vorherige Aussage hilft der AlloyDB-KI, Nutzern auf Fragen in natürlicher Sprache qualitativ hochwertigere Antworten zu liefern.

2. Führen Sie den folgenden Befehl aus, um die allgemeinen Kontexte für die angegebene Konfiguration aufzurufen:

   SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);
   

Schemakontext generieren und prüfen

Der Schemakontext beschreibt Schemaobjekte wie Tabellen, Ansichten, materialisierte Ansichten und Spalten. Dieser Kontext wird als COMMENT jedes Schemaobjekts gespeichert.

1. Rufen Sie die folgenden APIs auf, um Kontexte für Schemaobjekte zu generieren. Die besten Ergebnisse erzielen Sie, wenn die Datenbanktabellen repräsentative Daten enthalten.

   -- For all schema objects (tables, views, materialized views and columns)
   -- within the scope of a provided nl_config.
   SELECT
     alloydb_ai_nl.generate_schema_context(
       'my_app_config' -- nl_config
     );
   

2. Prüfen Sie die generierten Schemakontexte mit dem folgenden Befehl.

   SELECT schema_object, object_context
   FROM alloydb_ai_nl.generated_schema_context_view;
   

   Die generierten Schemakontexte werden in der vorherigen Ansicht gespeichert.

3. Optional: Aktualisieren Sie die generierten Schemakontexte.

   SELECT
     alloydb_ai_nl.update_generated_relation_context(
       'my_schema.my_table',
       'This table contains archival records, if you need latest records use records_new table.'
     );
   
   SELECT
     alloydb_ai_nl.update_generated_column_context(
       'my_schema.my_table.column1',
       'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
     );
   

4. Wenden Sie den Kontext an. Wenn Sie den Kontext anwenden, tritt er sofort in Kraft und wird aus der generated_schema_context_view gelöscht.

   -- For all schema objects (tables, views, materialized views and columns) 
   -- within the scope of nl_config.
   SELECT 
     alloydb_ai_nl.apply_generated_schema_context(
       'my_app_config' --nl_config
     );
   

5. Optional: Prüfen Sie den generierten Kontext. Mit der folgenden API können Sie die Schemakontexte prüfen, die beim Generieren von SQL-Anweisungen verwendet werden.

   -- For table, view or materialized view.
   SELECT
     alloydb_ai_nl.get_relation_context(
       'my_schema.my_table'
     );
   
   -- For column.
   SELECT
     alloydb_ai_nl.get_column_context(
       'my_schema.my_table.column1'
     );
   

6. Optional: Legen Sie den Schemakontext manuell fest.

   -- For table, view or materialized view.
   SELECT 
     alloydb_ai_nl.set_relation_context(
       'my_schema.my_table',
       'One-to-many mapping from product to categories'
     );
   
   -- For column.
   SELECT 
     alloydb_ai_nl.set_column_context(
       'my_schema.my_table.column1',
       'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
     );
   

Abfragevorlagen erstellen

Sie können Vorlagen hinzufügen, um die Qualität von Anwendungen mit generativer KI zu verbessern, die mit LLMs erstellt wurden. Eine Abfragevorlage ist eine ausgewählte Reihe repräsentativer oder gängiger Fragen in natürlicher Sprache mit entsprechenden SQL-Abfragen sowie Erklärungen, die eine deklarative Begründung für die NL2SQL-Generierung (Natural Language to SQL) liefern. Vorlagen werden in erster Linie von der Anwendung angegeben. Sie können aber auch automatisch von der alloydb_ai_nl-Erweiterung anhand häufig verwendeter SQL-Abfragen generiert werden. Jede Vorlage muss einem nl_config zugeordnet sein.

Die alloydb_ai_nl-Erweiterung verwendet eine template_store, um relevante SQL-Vorlagen dynamisch in den Prozess zum Generieren einer SQL-Anweisung zur Beantwortung der Frage des Nutzers einzubinden. template_store identifiziert Vorlagen mit ähnlichen Absichten wie die gestellte Frage in natürlicher Sprache, identifiziert die entsprechende parametrisierte SQL-Anweisung und synthetisiert eine SQL-Anweisung, indem Parameter mit Werten aus der Frage in natürlicher Sprache instanziiert werden. Wenn es jedoch keine Vorlage mit derselben Absicht wie die Frage des Nutzers gibt, verwendet alloydb_ai_nl alle relevanten Vorlagen und Kontexte, um eine SQL-Anweisung zu erstellen.

Sie fügen Vorlagen hinzu, indem Sie die Frage (mit einem Parameter namens intent) und die SQL-Abfrage angeben.

Führen Sie den folgenden Befehl aus, um dem Vorlagenspeicher eine Vorlage hinzuzufügen:

SELECT
  alloydb_ai_nl.add_template(
    nl_config => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    sql => 'SELECT COUNT(T1.account_id)
            FROM bird_dev_financial.account AS T1
            INNER JOIN bird_dev_financial.loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN bird_dev_financial.district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

Wenn check_intent TRUE ist, führt alloydb_ai_nl eine semantische Prüfung durch, um zu bestätigen, dass die angegebene Absicht mit der übergebenen SQL-Anweisung übereinstimmt. Wenn die Absicht nicht mit der SQL-Anweisung übereinstimmt, wird die Vorlage nicht hinzugefügt.

Vorlagen automatisch generieren

Sobald Sie einen repräsentativen Datensatz in Ihren Tabellen haben, empfehlen wir, SQL-Abfragen auszuführen, die den häufig gestellten Fragen Ihrer Endnutzer entsprechen. Es ist wichtig, dass die Abfragen gute Abfragepläne haben und eine gute Leistung erzielen.

Nachdem Sie die Abfragen ausgeführt haben, kann AlloyDB AI Natural Language automatisch Vorlagen basierend auf dem Abfrageverlauf generieren. Sie können die folgenden APIs aufrufen, um Vorlagen zu generieren. Sie müssen die generierten Vorlagen prüfen und anwenden, bevor sie wirksam werden.

Die automatische Vorlagenerstellung basiert auf den am häufigsten verwendeten Abfragen im Abfrageprotokoll google_db_advisor_workload_statements. Die Abfragen werden anhand der folgenden Kriterien gefiltert:

• SELECT-Anweisungen
• Ausführbare Dateien: Die Abfrage kann mit dem Befehl EXPLAIN erfolgreich verarbeitet werden.
• Keine Duplizierung: Die Abfrage wurde noch nicht verwendet, um Vorlagen zu generieren.
• Alle referenzierten Tabellen und Ansichten fallen in den Geltungsbereich der nl_config.

So generieren, überprüfen und wenden Sie Vorlagen automatisch an:

1. So fordern Sie AlloyDB auf, Vorlagen basierend auf Ihrem Abfrageverlauf zu generieren:

   SELECT 
     alloydb_ai_nl.generate_templates(
       'my_app_config', 
   );
   

   In der bereitgestellten Ansicht alloydb_ai_nl.generated_templates_view können Sie sich die generated_templates ansehen.

   Die folgende Ausgabe zeigt die Anzahl der generierten Vorlagen:

   -[ RECORD 1 ]------+--
   generate_templates | 1
   

2. Sehen Sie sich die generierten Vorlagen in der Ansicht generated_templates_view an.

   SELECT * 
   FROM alloydb_ai_nl.generated_templates_view;
   

   Im Folgenden finden Sie ein Beispiel für die zurückgegebene Ausgabe:

   -[ RECORD 1 ]----------------------------------------------------------------
   id          | 1
   config      | my_app_config
   type        | Template
   manifest    | How many clients have a birth year of a given number?
   nl          | How many clients have a birth year of 1997?
   sql         | select count(*) from public.client as T where  
                to_char(T.birth_date::timestamp, 'YYYY') = '1997';
   intent      | How many clients have a birth year of 1997?
   psql        | select count(*) from public.client as T where  
                to_char(T.birth_date::timestamp, 'YYYY') = $1;
   pintent     | How many clients have a birth year of $1?
   comment     |
   explanation |
   weight      | 1
   

3. Führen Sie den folgenden Beispielbefehl aus, um eine generierte Vorlage zu aktualisieren:

   SELECT alloydb_ai_nl.update_generated_template(
     id => 1,
     manifest => 'How many clients are born in a given year?',
     nl => 'How many clients are born in 1997?',
     intent => 'How many clients are born in 1997?',
     pintent => 'How many clients are born in $1?'
   
   );
   

4. Wenden Sie die Vorlagen an. Die von Ihnen angewendeten Vorlagen werden sofort dem Vorlagenspeicher hinzugefügt und aus der Ansicht „Überprüfung“ gelöscht.

   -- For all templates generated under the nl config.
   SELECT
     alloydb_ai_nl.apply_generated_templates('my_app_config');
   

Sicherheit für natürliche Sprache konfigurieren

Informationen zum Konfigurieren der Sicherheit für die natürliche Sprache von AlloyDB AI finden Sie unter Sicherheit von Datenanwendungen mit parametrisierten sicheren Ansichten verwalten.

Konzepttypen und Wertindex definieren

Sie definieren Konzepttypen und Wertindizes, um ein besseres Verständnis der gestellten Fragen zu erhalten. Ein Konzepttyp ist eine Kategorie oder Klasse von Entitäten, die die semantische Bedeutung von Wörtern und Wortgruppen anstelle ihrer wörtlichen Form identifiziert.

Zwei Ländernamen können beispielsweise identisch sein, auch wenn der eine Ländername in Großbuchstaben geschrieben ist, z. B. USA, und der andere Ländername in Kleinbuchstaben, z. B. usa. In diesem Fall ist „Landname“ der Konzepttyp. Weitere Beispiele für Begriffstypen sind Personennamen, Ortsnamen und Datumsangaben.

Ein Wertindex ist ein Index, der auf den Werten in den Spalten basiert, die Teil der Natural Language-Konfiguration nl_config sind. Er basiert auf den Konzepttypen, die mit den einzelnen Spalten verknüpft sind. Ein Werteindex ermöglicht eine effiziente Übereinstimmung von Wertbegriffen für die gestellte Frage und Werten in der Datenbank.

Folgen Sie der Anleitung und verwenden Sie die Beispieldaten, um Konzepttypen und einen Wertindex zu definieren. In den Beispielen wird eine Spalte einem Konzepttyp zugeordnet, ein Werteindex erstellt und aktualisiert und ein Synonymsatz für eine Wertesuche verwendet.

1. Führen Sie die folgende Abfrage aus, um eine Spalte mit einem Konzepttyp zu verknüpfen:

   SELECT
     alloydb_ai_nl.associate_concept_type(
       column_names_in => 'my_schema.country.country_name',
       concept_type_in => 'country_name',
       nl_config_id_in => 'my_app_config'
     );
   

2. Wenn Sie einen Wertindex basierend auf allen Spalten erstellen möchten, die Teil einer Natural Language-Konfiguration sind und mit einem Konzepttyp verknüpft sind, führen Sie die folgende Anweisung aus:

   SELECT
     alloydb_ai_nl.create_value_index(
       nl_config_id_in => 'my_app_config'
     );
   

3. Wenn Sie neuen Spalten Konzepttypen zuordnen, aktualisieren Sie den Wertindex, damit die Änderungen berücksichtigt werden.

   SELECT
     alloydb_ai_nl.refresh_value_index(
       nl_config_id_in => 'my_app_config'
     );
   

4. Wenn Sie möchten, dass die AlloyDB-KI Synonyme eines Werts in natürlicher Sprache abgleicht, führen Sie die folgende Beispielanweisung aus:

   SELECT
     alloydb_ai_nl.insert_synonym_set(
       ARRAY [
         'USA',
         'US',
         'United States',
         'United States of America'
       ]
     );
   

   Auch wenn in den Daten in Ihren Tabellen ein bestimmter Wert verwendet wird, z. B. United States, um ein Land anzugeben, können Sie einen Synonyme-Satz definieren, der alle Synonyme für United States enthält. Wenn einer der Synonyme in der Frage in natürlicher Sprache vorkommt, gleicht AlloyDB AI Natural Language die Synonyme mit den Werten in Ihren Tabellen ab.

5. Führen Sie eine Wertesuche durch, um anhand eines Arrays von Wertbegriffen die richtigen Datenbankwerte zu finden.

   SELECT
     alloydb_ai_nl.get_concept_and_value(
       value_phrases_in => ARRAY['United States'],
       nl_config_id_in  => 'my_app_config'
     );
   

   Wenn ein Nutzer beispielsweise eine Frage wie „Wie hoch ist die Bevölkerungszahl der USA?“ stellt, die die folgende get_sql-Abfrage verwendet, verwendet die AlloyDB-KI für natürliche Sprache die Funktion get_concept_and_value mit der Wertphrase United States, um eine Fuzzy-Suche in den Wertindizes durchzuführen. Bei der Fuzzy-Suche werden Übereinstimmungen gefunden, auch wenn die Suchanfrage nicht genau mit den entsprechenden Daten übereinstimmt.

   Die Natural Language-Funktion sucht nach einem Ergebnis, dem Wert USA, der der Suchanfrage nahekommt, und generiert anhand dieses Ergebnisses die SQL-Abfrage.

   SELECT
     alloydb_ai_nl.get_sql(
       nl_config_id    => 'my_app_config',
       nl_question     => 'What is the population of the United States?',
       additional_info => json_build_object('enrich_nl_question', TRUE)
     ) ->> 'sql';
   

   In der folgenden Tabelle sind die integrierten Konzepttypen aufgeführt, die von AlloyDB AI in natürlicher Sprache definiert wurden.

   Name des Konzepts	Beschreibung
   generic_entity_name	Für einen generischen Entitätsnamen kann eine einzelne Spalte vom Typ „String“ verwendet werden. Beispiel: SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
   country_name, city_name, region_name	Namen von Ländern, Städten und Regionen Die Verwendung entspricht genau der des Konzepttyps generic_entity_name.
   full_person_name	Der Name der Person, bestehend aus Vorname, Nachname und zweitem Vornamen. Für den vollständigen Namen einer Person können bis zu drei Spalten vom Typ „String“ verwendet werden. Sie können beliebige Spalten überspringen, wenn Sie Namensspalten mit full_person_name verknüpfen. Beispiel: SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
   ssn	Eine einzelne Stringspalte mit einer Sozialversicherungsnummer. Beispiel: SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
   date	Ein Datum oder ein Zeitstempel. Beispiel: SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

SQL-Anweisungen aus Eingaben in natürlicher Sprache generieren

Mit der AlloyDB-KI für natürliche Sprache können Sie SQL-Anweisungen aus Eingaben in natürlicher Sprache generieren. Wenn Sie die generierte SQL-Anweisung ausführen, werden die Daten aus der Datenbank bereitgestellt, die Sie zur Beantwortung der Frage in natürlicher Sprache benötigen.

1. Im folgenden Beispiel wird gezeigt, wie Sie mit der Funktion alloydb_ai_nl.get_sql Ergebnisse in natürlicher Sprache aus Ihrer Datenbank abrufen:

   SELECT
     alloydb_ai_nl.get_sql(
       'my_app_config', -- nl_config
       'What is the sum that client number 4''s account has following transaction 851?' -- nl question
     );
   

   Die folgende JSON-Ausgabe wird zurückgegeben:

   {
     "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
     "prompt": "",
     "retries": 0,
     "error_msg": "",
     "nl_question": "What is the sum that client number 4's account has following transaction 851?"
   }
   

2. Optional: Wenn Sie die generierte SQL-Abfrage als Textstring extrahieren möchten, fügen Sie ->>'sql' hinzu:

   SELECT
     alloydb_ai_nl.get_sql(
       'my_app_config', -- nl_config
       'What is the sum that client number 4''s account has following transaction 851?' -- nl question
     ) ->> 'sql';
   

   Mit dem Operator ->> wird ein JSON-Wert als Text extrahiert. Die Funktion alloydb_ai_nl.get_sql gibt ein JSON-Objekt zurück. Das ist der Teil der Anweisung, mit dem der mit dem Schlüssel sql verknüpfte Wert abgerufen wird. Dieser Wert ist die generierte SQL-Abfrage.

Testen und optimieren

Wenn Sie bessere automatisch generierte Abfragen erhalten möchten, fügen Sie einen besseren Kontext, Abfragevorlagen und Wertindexe hinzu und wiederholen Sie den Vorgang, bis Sie die gewünschten Ergebnisse erzielen.

Nächste Schritte

• Weitere Informationen zu Anwendungsfällen und wichtigen Funktionen von AlloyDB AI Natural Language
• SQL mit AlloyDB AI in natürlicher Sprache generieren
• Weitere Informationen zum Suchen in Ihren relationalen Daten, die in AlloyDB in Google Agentspace gespeichert sind, mit AlloyDB AI in natürlicher Sprache (Vorabversion)