Auf dieser Seite wird beschrieben, wie Sie selbst erstellten Kontext für KI-Datenagenten bereitstellen, die Datenbankdatenquellen verwenden.
Der selbst erstellte Kontext ist eine Anleitung, die Daten-KI-Agent-Inhaber bereitstellen können, um das Verhalten eines Daten-KI-Agenten zu beeinflussen und die Antworten der API zu optimieren. Ein effektiver selbst erstellter Kontext liefert Ihren Daten-KI-Agenten der Conversational Analytics API nützliche Informationen, um Fragen zu Ihren Datenquellen zu beantworten.
Bei Datenbankdatenquellen wie AlloyDB, GoogleSQL for Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL stellen Sie den erstellten Kontext bereit, indem Sie ihn zuerst in der Datenbank definieren und speichern und dann in Ihrer Datenquellenreferenz darauf verweisen. In den Beispielen auf dieser Seite wird die Methode QueryData verwendet.
Wenn Sie Kontext mit hoher Genauigkeit bereitstellen, kann die API genauere und relevantere SQL-Abfragen und Antworten generieren.
Hinweis
- Sie benötigen einen KI-Datenagenten mit hochgeladenem Agentenkontext für die Datenbank, die Sie abfragen möchten. Weitere Informationen finden Sie in der Dokumentation zu Daten-Agenten für AlloyDB, Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL. Informationen zu Spanner Graph finden Sie unter Kontextsätze in Spanner Studio verwalten.
- Wenn Sie Kontextsets für Datenbankdatenquellen erstellen, hochladen und verwalten möchten, aktivieren Sie die Knowledge Catalog API und weisen Sie dem IAM-Nutzer oder -Dienstkonto auf Projektebene die Rolle „Dataplex Catalog Editor“ (
roles/dataplex.catalogEditor) oder „Dataplex Catalog Admin“ (roles/dataplex.catalogAdmin) zu. Weitere Informationen finden Sie unter Berechtigungen für Kontextgruppen. Aktivieren Sie die Cloud SQL Data API für Ihre Instanz so:
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_APIErsetzen Sie
INSTANCE_IDdurch die ID Ihrer Cloud SQL for MySQL- oder Cloud SQL for PostgreSQL-Instanz.Außerdem müssen Sie einem IAM-Nutzer oder -Dienstkonto Datenbankberechtigungen erteilen. Weitere Informationen finden Sie unter Datenbankberechtigungen für einen einzelnen IAM-Nutzer oder ein einzelnes Dienstkonto in Cloud SQL for MySQL gewähren und Datenbankberechtigungen für einen einzelnen IAM-Nutzer oder ein einzelnes Dienstkonto in Cloud SQL for PostgreSQL gewähren.
Kontext mit QueryData bereitstellen
Beim Aufrufen der Methode QueryData geben Sie die Datenquelle und Kontextinformationen im Feld QueryDataRequest.context.datasourceReferences an. Für Datenbankdatenquellen müssen Sie eine der folgenden Optionen verwenden:
alloydbfür AlloyDB for PostgreSQLspanner_referencefür GoogleSQL für Spannercloud_sql_referencefür Cloud SQL for MySQL und Cloud SQL for PostgreSQL
In diesen Verweisen geben Sie die Datenbank und die Tabellen mit dem Feld databaseReference an. Wenn Sie verfassten Kontext einbeziehen möchten, müssen Sie auch eine agentContextReference angeben, die auf eine context_set_id verweist.
Beispiel für eine QueryData-Anfrage mit selbst erstelltem Kontext
Das folgende Beispiel zeigt eine QueryData-Anfrage, die alloydb verwendet. Das Feld agent_context_reference.context_set_id wird verwendet, um auf vordefinierten Kontext zu verweisen, der in der Datenbank gespeichert ist.
AlloyDB
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "alloydb": { "database_reference": { "project_id": "data-agents-project", "region": "us-central1", "cluster_id": "sqlgen-magic", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
GoogleSQL für Spanner
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "spanner_reference" { "database_reference" { "engine": "GOOGLE_SQL" "project_id": "data-agents-project" "instance_id": "evalbench" "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Spanner Graph
{ "parent": "projects/data-agents-project/locations/global", "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "data-agents-project", "instance_id": "data-agents-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-central1/contextSets/fingraph-assistant" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Cloud SQL for MySQL
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "cloud_sql_reference": { "database_reference": { "engine": "MYSQL" "project_id": "data-agents-project", "region": "us-central1", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Cloud SQL for PostgreSQL
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "cloud_sql_reference": { "database_reference": { "engine": "POSTGRES" "project_id": "data-agents-project", "region": "us-central1", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Der Anfragetext enthält die folgenden Felder:
prompt: Die Frage des Endnutzers in natürlicher Sprache.context: Enthält Informationen zu den Datenquellen.datasource_references: Gibt den Typ der Datenquelle an.alloydb: Erforderlich, wenn die Datenbank abgefragt wird. Dieses Feld ändert sich je nach der Datenbank, die Sie abfragen.database_reference: Gibt Informationen zu Ihrer Datenbankinstanz an.engine: Die Datenbank-Engine oder der SQL-Dialekt. Optional für AlloyDB. Legen Sie für Spanner-DatenbankenGOOGLE_SQLfest. Legen Sie für Cloud SQL for MySQL-InstanzenMYSQLfest. Legen Sie für Cloud SQL for PostgreSQL-InstanzenPOSTGRESQLfest.project_id: Die Projekt-ID der Datenbankinstanz.region: Die Region der Datenbankinstanz.cluster_id: Die Cluster-ID der Datenbankinstanz.instance_id: Die Instanz-ID der Datenbank.database_id: Die ID der Datenbank.graph_ids: Erforderlich für Spanner Graph. Eine Liste der Namen von Eigenschaftsgraphen in der Spanner-Datenbank, die abgefragt werden sollen (z. B.["FinGraph"]). Wenn Siegraph_idsweglassen, generiert QueryData GoogleSQL-Abfragen für die zugrunde liegenden Tabellen anstelle von GQL-Abfragen.
agent_context_reference: Links zu verfasstem Kontext in der Datenbank.context_set_id: Die in der Datenbank gespeicherte Kontext-ID des KI-Agenten. Weitere Informationen zum Ermitteln der Kontextsatz-ID finden Sie in der Dokumentation zu AlloyDB, Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL. Informationen zu Spanner Graph finden Sie unter Kontextsatz-ID finden.
generationOptions: Konfiguriert den Typ der zu generierenden Ausgabe.generate_query_result: Legen Sie „true“ fest, um die Abfrageergebnisse zu generieren und zurückzugeben.generate_natural_language_answer: Optional. Wenn auf „true“ gesetzt, wird eine Antwort in natürlicher Sprache generiert.generate_explanation: Optional. Wenn diese Option auf „true“ gesetzt ist, wird eine Erklärung der SQL-Abfrage generiert.generate_disambiguation_question: Optional. Wenn diese Option auf „true“ gesetzt ist, werden Fragen zur Mehrdeutigkeitsauflösung generiert, wenn die Abfrage mehrdeutig ist.
QueryData-Beispielantwort
Hier ist ein Beispiel für eine erfolgreiche Antwort auf einen QueryData-Aufruf:
{
"generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
"intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
"query_result": {
"columns": [
{
"name": "count"
}
],
"rows": [
{
"values": [
{
"value": "2"
}
]
}
],
"total_row_count": 1
},
"natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}