KI-Agents in Azure-Datenbank für PostgreSQL

2025-06-22

Künstliche Intelligenz (KI)-Agenten transformieren, wie Anwendungen mit Daten interagieren, indem sie große Sprachmodelle (LLMs) mit externen Tools und Datenbanken kombinieren. Agents ermöglichen die Automatisierung komplexer Workflows, verbessern die Genauigkeit des Abrufens von Informationen und erleichtern Schnittstellen in natürlicher Sprache zu Datenbanken. In diesem Artikel erfahren Sie, wie Sie intelligente KI-Agents erstellen, die Ihre Daten in der Azure-Datenbank für PostgreSQL durchsuchen und analysieren können. Wir durchlaufen die Einrichtung, Implementierung und Tests mithilfe einer assistierenden Person für juristische Recherchen als Beispiel.

Was sind KI-Agents?

KI-Agents gehen über einfache Chatbots hinaus, indem sie große Sprachmodelle (LLMs) mit externen Tools und Datenbanken kombinieren. Im Gegensatz zu eigenständigen LLMs oder Standard-RAG-Systemen können KI-Agents:

Plan: Aufteilen komplexer Aufgaben in kleinere, sequenzielle Schritte.
Verwenden Sie Tools: Verwenden Sie APIs, Codeausführung und Suchsysteme, um Informationen zu sammeln oder Aktionen auszuführen.
Wahrnehmung: Verstehen und Verarbeiten von Eingaben aus verschiedenen Datenquellen.
Denken Sie daran: Speichern und Zurückrufen vorheriger Interaktionen für eine bessere Entscheidungsfindung.

Durch die Verbindung von KI-Agents mit Datenbanken wie Azure Database for PostgreSQL können Agents präzisere, kontextbezogene Antworten basierend auf Ihren Daten bereitstellen. KI-Agenten gehen über einfache zwischenmenschliche Kommunikation hinaus und führen Aufgaben basierend auf natürlicher Sprache aus. Diese Aufgaben erfordern traditionell codierte Logik; Agents können jedoch die für die Ausführung erforderlichen Aufgaben basierend auf dem vom Benutzer bereitgestellten Kontext planen.

Implementierung von KI-Agents

Die Implementierung von KI-Agents mit Azure Database for PostgreSQL umfasst die Integration erweiterter KI-Funktionen mit robusten Datenbankfunktionen, um intelligente, kontextabhängige Systeme zu erstellen. Durch die Nutzung von Tools wie Vektorsuche, Einbettungen und Azure AI Agent Service können Entwickler Agents erstellen, die in der Lage sind, Abfragen natürlicher Sprachen zu verstehen, relevante Daten abzurufen und umsetzbare Erkenntnisse bereitzustellen. In diesem Abschnitt wird der schrittweise Prozess zum Einrichten, Konfigurieren und Bereitstellen von KI-Agents beschrieben, wodurch eine nahtlose Interaktion zwischen KI-Modellen und Ihrer PostgreSQL-Datenbank ermöglicht wird.

Rahmenwerke

Verschiedene Frameworks und Tools können die Entwicklung und Bereitstellung von KI-Agents erleichtern. All diese Frameworks unterstützen die Verwendung von Azure Database for PostgreSQL als Tool

Implementierungsbeispiel

Wir verwenden den Azure AI Agent Service für die Agentplanung, Toolverwendung und Wahrnehmung bei Verwendung der Azure-Datenbank für PostgreSQL als Tool für Vektordatenbank und semantische Suchfunktionen.

Im Lernprogramm erstellen wir einen KI-Agent, der juristische Teams bei der Recherche relevanter Fälle hilft, um ihre Kunden in Washington zu unterstützen. Unser Agent:

Akzeptieren Sie natürliche Sprachabfragen zu rechtlichen Situationen.
Verwenden Sie die Vektorsuche in der Azure-Datenbank für PostgreSQL, um relevante Fallvorfälle zu finden.
Analysieren und zusammenfassen Sie die Ergebnisse in einem hilfreichen Format für Rechtsexperten.

Voraussetzungen

Aktivieren und Konfigurierenazure_ai & pg_vector Erweiterung.
Erstellen Sie ein Azure AI Foundry-Projekt.
Bereitstellen von Modellengpt-4o-mini & text-embedding-small
Installieren Sie Visual Studio Code.
Installieren Sie die Python-Erweiterung .
Installieren Sie Python 3.11.x.
Installieren Sie Azure CLI.(neueste Version)

Hinweis

Sie benötigen den Schlüssel und Endpunkt aus den bereitgestellten Modellen, die Sie für den Agenten erstellt haben.

Erste Schritte

Alle Code- und Beispieldatensätze sind in diesem GitHub-Repository verfügbar.

Schritt 1: Einrichten der Vektorsuche in Azure-Datenbank für PostgreSQL

Zunächst bereiten wir unsere Datenbank zum Speichern und Durchsuchen von Rechtsfalldaten mithilfe von Vektoreinbettungen vor:

Einrichten der Umgebung

Bei Verwendung von macOS /bash:

python -m venv .pg-azure-ai 
source .pg-azure-ai/bin/activate 
pip install -r requirements.txt

Windows/ PowerShell

python -m venv .pg-azure-ai 
.pg-azure-ai \Scripts\Activate.ps1 
pip install -r requirements.txt

Windows/cmd.exe:

python -m venv .pg-azure-ai 
.pg-azure-ai \Scripts\activate.bat 
pip install -r requirements.txt

Konfigurieren von Umgebungsvariablen

Erstellen Sie eine .env Datei mit Ihren Anmeldeinformationen:

AZURE_OPENAI_API_KEY="" 
AZURE_OPENAI_ENDPOINT="" 
EMBEDDING_MODEL_NAME="" 
AZURE_PG_CONNECTION=""

Laden von Dokumenten und Vektoren

Die Python-Datei load_data/main.py dient als zentraler Einstiegspunkt zum Laden von Daten in Azure Database for PostgreSQL. Der Code verarbeitet die Beispielfälledaten, einschließlich Informationen zu Fällen in Washington.

Allgemeine Details zu main.py:

Datenbankeinrichtung und Tabellenerstellung: Erstellt erforderliche Erweiterungen, richtet OpenAI-API-Einstellungen ein und verwaltet Datenbanktabellen, indem vorhandene gelöscht und neue zum Speichern von Falldaten erstellt werden.
Datenaufnahme: Dieser Prozess liest Daten aus einer CSV-Datei und fügt sie in eine temporäre Tabelle ein, verarbeitet und überträgt sie dann in die Hauptfalltabelle.
Einbettungsgenerierung: Fügt eine neue Spalte für Einbettungen in die Falltabelle hinzu und generiert Einbettungen für Fallmeinungen mithilfe der OpenAI-API, die sie in der neuen Spalte speichert. Der Einbettungsprozess dauert ca. 3-5 Minuten.

Führen Sie zum Starten des Datenladevorgangs den folgenden Befehl aus dem verzeichnis load_data aus:

python main.py

Dies ist die Ausgabe von main.py:

Extensions created successfully 
OpenAI connection established successfully 
The case table was created successfully 
Temp cases table created successfully 
Data loaded into temp_cases_data table successfully 
Data loaded into cases table successfully.
Adding Embeddings will take a while, around 3-5 mins.
Embeddings added successfully All Data loaded successfully!

Schritt 2: Erstellen eines Postgres-Tools für den Agent

Wir konfigurieren KI-Agent-Tools zum Abrufen von Daten aus Postgres und verwenden dann das Azure AI Agent Service SDK , um Ihren KI-Agent mit der Postgres-Datenbank zu verbinden.

Definieren einer Funktion, die Ihr Agent aufrufen soll

Definieren Sie zunächst eine Funktion für den Agent, die aufgerufen werden soll, indem Sie die Struktur und alle erforderlichen Parameter in einer Docstring-Datei beschreiben. Schließen Sie alle Funktionsdefinitionen in eine einzelne Datei ein, legal_agent_tools.py, die Sie dann in Ihr Hauptskript importieren können.

def vector_search_cases(vector_search_query: str, start_date: datetime ="1911-01-01", end_date: datetime ="2025-12-31", limit: int = 10) -> str:
    """
 Fetches the case information in Washington State for the specified query.

 :param query(str): The query to fetch cases specifically in Washington.
 :type query: str
 :param start_date: The start date for the search defaults to "1911-01-01"
 :type start_date: datetime, optional
 :param end_date: The end date for the search, defaults to "2025-12-31"
 :type end_date: datetime, optional
 :param limit: The maximum number of cases to fetch, defaults to 10
 :type limit: int, optional

 :return: Cases information as a JSON string.
 :rtype: str
 """
        
 db = create_engine(CONN_STR)
    
 query = """
 SELECT id, name, opinion, 
 opinions_vector <=> azure_openai.create_embeddings(
 'text-embedding-3-small', %s)::vector as similarity
 FROM cases
 WHERE decision_date BETWEEN %s AND %s
 ORDER BY similarity
 LIMIT %s;
 """
    
    # Fetch cases information from the database
 df = pd.read_sql(query, db, params=(vector_search_query,datetime.strptime(start_date, "%Y-%m-%d"), datetime.strptime(end_date, "%Y-%m-%d"),limit))

 cases_json = json.dumps(df.to_json(orient="records"))
    return cases_json

Schritt 3: Erstellen und Konfigurieren des KI-Agents mit Postgres

Jetzt richten wir den KI-Agent ein und integrieren ihn in unser PostgreSQL-Tool. Die Python-Datei src/simple_postgres_and_ai_agent.py dient als zentraler Einstiegspunkt zum Erstellen und Verwenden Ihres Agents.

Allgemeine Details zu simple_postgres_and_ai_agent.py:

Erstellen Sie einen Agent: Initialisiert den Agent in Ihrem Azure AI-Projekt mit einem bestimmten Modell.
Fügen Sie Das Tool Postgres hinzu: Während der Agentinitialisierung wird das Postgres-Tool für die Vektorsuche in Ihrer Datenbank hinzugefügt.
Erstellen eines Threads: Richtet einen Kommunikationsthread ein. Dies wird verwendet, um Nachrichten an den Agent zu senden, die verarbeitet werden sollen.
Führen Sie das Tool Agent und Call Postgres aus: Verarbeitet die Abfrage des Benutzers mit dem Agent und den Tools. Der Agent kann planen, welche Werkzeuge er verwenden sollte, um die richtige Antwort zu erhalten. In diesem Anwendungsfall ruft der Agent das Tool Postgres basierend auf der Funktionssignatur und Docstring auf, um eine Vektorsuche durchzuführen und die relevanten Daten abzurufen, um die Frage zu beantworten.
Anzeigen der Antwort des Agents: Mit dieser Funktion wird die Antwort des Agents auf die Abfrage des Benutzers ausgegeben.

Projektverbindungszeichenfolge in Azure AI Foundry finden

In Ihrem Azure AI Foundry-Projekt finden Sie ihre Projektverbindungszeichenfolge auf der Seite "Übersicht" des Projekts. Wir verwenden diese Zeichenfolge, um das Projekt mit dem AI-Agent-SDK zu verbinden. Fügen Sie diese Zeichenfolge zur env-Datei hinzu.

Screenshot der Projekteinrichtungsseite.

Verbindungskonfiguration

Fügen Sie diese Variablen zur env-Datei im Stammverzeichnis hinzu:

PROJECT_CONNECTION_STRING=" " 
MODEL_DEPLOYMENT_NAME="gpt-4o-mini" 
AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED="true"

### Create the Agent with Tool Access
We created the agent in the AI Foundry project and added the Postgres tools needed to query the Database. The code snippet below is an excerpt from the file [simple_postgres_and_ai_agent.py](https://github.com/Azure-Samples/postgres-agents/blob/main/src/simple_postgres_and_ai_agent.py).

# Create an Azure AI Client
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

# Initialize agent toolset with user functions
functions = FunctionTool(user_functions)
toolset = ToolSet()
toolset.add(functions)

agent = project_client.agents.create_agent(
    model= os.environ["MODEL_DEPLOYMENT_NAME"], 
    name="legal-cases-agent",
    instructions= "You are a helpful legal assistant who can retrieve information about legal cases.", 
    toolset=toolset
)

Kommunikationsthread erstellen

Dieser Codeausschnitt zeigt, wie Sie einen Agentthread und eine Nachricht erstellen, die der Agent in einer Ausführung verarbeitet.

# Create thread for communication
thread = project_client.agents.create_thread()

# Create message to thread
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="Water leaking into the apartment from the floor above. What are the prominent legal precedents in Washington regarding this problem in the last 10 years?"
)

Verarbeiten der Anforderung

Dieser Codeausschnitt erstellt eine Ausführung für den Agent zum Verarbeiten der Nachricht und verwendet die entsprechenden Tools, um das beste Ergebnis bereitzustellen.

Mit dem Tool kann der Agent Postgres und die Vektorsuche mit der Abfrage "Wasser, das von oben in die Wohnung eindringt" aufrufen, um die benötigten Daten abzurufen, die erforderlich sind, um die Frage bestmöglich zu beantworten.

from pprint import pprint

# Create and process agent run in thread with tools
run = project_client.agents.create_and_process_run(
thread_id=thread.id, 
agent_id=agent.id
)

# Fetch and log all messages
messages = project_client.agents.list_messages(thread_id=thread.id)
pprint(messages['data'][0]['content'][0]['text']['value'])

Ausführen des Agents

Führen Sie zum Ausführen des Agents den folgenden Befehl aus dem src-Verzeichnis aus:

python simple_postgres_and_ai_agent.py

Der Agent erzeugt ein ähnliches Ergebnis mithilfe des Azure Database for PostgreSQL-Tools, um auf Falldaten zuzugreifen, die in der Postgres-Datenbank gespeichert sind.

Codeschnipsel der Ausgabe des Agents:

1.     Pham v. Corbett

Citation: Pham v. Corbett, No. 4237124
Summary: This case involved tenants who counterclaimed against their landlord for relocation assistance and breached the implied warranty of habitability due to severe maintenance issues, including water and sewage leaks. The trial court held that the landlord had breached the implied warranty and awarded damages to the tenants.

2.     Hoover v. Warner

Citation: Hoover v. Warner, No. 6779281
Summary: The Warners appealed a ruling finding them liable for negligence and nuisance after their road grading project caused water drainage issues affecting Hoover's property. The trial court found substantial evidence supporting the claim that the Warners' actions impeded the natural water flow and damaged Hoover's property.

Schritt 4: Testen und Debuggen mit Azure AI Foundry Playground

Nachdem Sie Ihren Agent mit dem Azure AI Agent SDK ausgeführt haben, wird der Agent in Ihrem Projekt gespeichert, und Sie können mit dem Agent im Agent-Playground experimentieren.

Verwenden des Agent-Playgrounds

Navigieren Sie zum Abschnitt "Agents" in Azure AI Foundry
Suchen Sie Ihren Agent in der Liste und wählen Sie ihn aus, um ihn zu öffnen
Verwenden Sie die Playground-Schnittstelle, um verschiedene rechtliche Abfragen zu testen
Testen Sie die Abfrage "Wasser, das aus der Etage darüber in die Wohnung eindringt, was sind die herausragenden rechtlichen Präzedenzfälle in Washington?" Der Agent wählt das richtige Werkzeug zur Verwendung aus und fordert das erwartete Ergebnis für diese Abfrage an. Verwenden Sie sample_vector_search_cases_output.json als Beispielausgabe.

Schritt 5: Debuggen mit Azure AI Foundry-Ablaufverfolgung

Beim Entwickeln des Agents mit dem Azure AI Foundry SDK können Sie den Agent mit Tracing debuggen. So können Sie die Aufrufe von Tools wie Postgres debuggen und sehen, wie der Agent jede Aufgabe koordiniert.

Debuggen mit Ablaufverfolgung

Wählen Sie „Ablaufverfolgung“ im Azure AI Foundry-Menü aus
Erstellen Sie eine neue Application Insights-Ressource oder wählen Sie eine vorhandene aus
Zeigen Sie detaillierte Ablaufverfolgungen der Vorgänge Ihres Agents an.

Erfahren Sie mehr darüber, wie Sie die Ablaufverfolgung mit dem KI-Agent und Postgres in der datei advanced_postgres_and_ai_agent_with_tracing.py auf GitHub einrichten.

Freigeben über