Agenci sztucznej inteligencji w usłudze Azure Database for PostgreSQL

Agenci sztucznej inteligencji przekształcają sposób interakcji aplikacji z danymi przez połączenie dużych modeli językowych (LLM) z zewnętrznymi narzędziami i bazami danych. Agenci umożliwiają automatyzację złożonych przepływów pracy, zwiększają dokładność pobierania informacji i ułatwiają interfejsy języka naturalnego dla baz danych.

W tym artykule opisano sposób tworzenia inteligentnych agentów sztucznej inteligencji, którzy mogą wyszukiwać i analizować dane w usłudze Azure Database for PostgreSQL. Przeprowadzi on proces konfigurowania, implementacji i testowania przy użyciu asystenta badań prawnych jako przykładu.

Co to są agenci sztucznej inteligencji?

Agenci sztucznej inteligencji wykraczają poza proste czatboty, łącząc modele LLM z zewnętrznymi narzędziami i bazami danych. W przeciwieństwie do autonomicznych systemów LLM lub standardowych systemów generacji rozszerzonej (RAG), agenci sztucznej inteligencji mogą:

Plan: podziel złożone zadania na mniejsze, sekwencyjne kroki.
Użyj narzędzi: użyj interfejsów API, wykonywania kodu i systemów wyszukiwania, aby zebrać informacje lub wykonać akcje.
Postrzeganie: Zrozumienie i przetwarzanie danych wejściowych z różnych źródeł danych.
Pamiętaj: Przechowuj i przywołuj poprzednie interakcje w celu lepszego podejmowania decyzji.

Łącząc agentów sztucznej inteligencji z bazami danych, takimi jak Azure Database for PostgreSQL, agenci mogą dostarczać dokładniejsze odpowiedzi kontekstowe na podstawie danych. Agenci sztucznej inteligencji wykraczają poza podstawową konwersację ludzką, aby wykonywać zadania na podstawie języka naturalnego. Te zadania tradycyjnie wymagały zakodowanej logiki. Jednak agenci mogą planować zadania wymagane do wykonania na podstawie kontekstu dostarczonego przez użytkownika.

Implementacja agentów sztucznej inteligencji

Implementowanie agentów sztucznej inteligencji za pomocą usługi Azure Database for PostgreSQL obejmuje integrowanie zaawansowanych funkcji sztucznej inteligencji z niezawodnymi funkcjami bazy danych w celu tworzenia inteligentnych systemów obsługujących kontekst. Korzystając z narzędzi, takich jak wyszukiwanie wektorowe, osadzanie i usługa agenta usługi Azure AI Foundry, deweloperzy mogą tworzyć agentów, którzy rozumieją zapytania języka naturalnego, pobierają odpowiednie dane i udostępniają praktyczne informacje.

W poniższych sekcjach opisano proces krok po kroku konfigurowania, konfigurowania i wdrażania agentów sztucznej inteligencji. Ten proces umożliwia bezproblemową interakcję między modelami sztucznej inteligencji a bazą danych PostgreSQL.

Frameworki

Różne struktury i narzędzia mogą ułatwić opracowywanie i wdrażanie agentów sztucznej inteligencji. Wszystkie te struktury obsługują używanie usługi Azure Database for PostgreSQL jako narzędzia:

Przykład implementacji

W przykładzie z tego artykułu użyto usługi Azure AI Foundry Agent Service do planowania agenta, korzystania z narzędzi i percepcji. Używa ona usługi Azure Database for PostgreSQL jako narzędzia do obsługi wektorowej bazy danych i funkcji wyszukiwania semantycznego.

W poniższych sekcjach opisano proces tworzenia agenta sztucznej inteligencji, który pomaga zespołom prawnym badać odpowiednie przypadki, aby wspierać swoich klientów w stanie Waszyngton. Agent:

Akceptuje zapytania w języku naturalnym dotyczące sytuacji prawnych.
Używa wyszukiwania wektorowego w usłudze Azure Database for PostgreSQL, aby znaleźć odpowiednie precedensy przypadków.
Analizuje i podsumowuje wyniki w przydatnym formacie dla prawników.

Wymagania wstępne

Włącz i skonfigurujazure_ai i pg_vector rozszerzenia.
Tworzenie projektu usługi Azure AI Foundry.
Wdrażanie modeligpt-4o-mini i text-embedding-small.
Zainstalowanie programu Visual Studio Code.
Zainstaluj rozszerzenie języka Python .
Zainstaluj środowisko Python 3.11.x.
Zainstaluj interfejs wiersza polecenia platformy Azure (najnowsza wersja).

Uwaga / Notatka

Potrzebujesz klucza i punktu końcowego z wdrożonych modeli utworzonych dla agenta.

Wprowadzenie

Cały kod i przykładowe zestawy danych są dostępne w tym repozytorium GitHub.

Krok 1. Konfigurowanie wyszukiwania wektorów w usłudze Azure Database for PostgreSQL

Najpierw przygotuj bazę danych do przechowywania i wyszukiwania danych sprawy prawnej przy użyciu osadzonych wektorów.

Konfigurowanie środowiska

Jeśli używasz systemów macOS i Bash, uruchom następujące polecenia:

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

Jeśli używasz systemu Windows i programu PowerShell, uruchom następujące polecenia:

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

Jeśli używasz systemów Windows i cmd.exe, uruchom następujące polecenia:

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

Skonfiguruj zmienne środowiskowe

Utwórz plik .env z użyciem swoich poświadczeń:

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

Ładowanie dokumentów i wektorów

Plik języka Python load_data/main.py służy jako centralny punkt wejścia do ładowania danych do usługi Azure Database for PostgreSQL. Kod przetwarza dane dla przykładowych przypadków, w tym informacje o przypadkach w Waszyngtonie.

Plik main.py:

Tworzy niezbędne rozszerzenia, konfiguruje ustawienia interfejsu API openAI i zarządza tabelami bazy danych, upuszczając istniejące i tworząc nowe na potrzeby przechowywania danych przypadków.
Odczytuje dane z pliku CSV i wstawia je do tabeli tymczasowej, a następnie przetwarza i przesyła je do tabeli głównej sprawy.
Dodaje nową kolumnę do osadzania w tabeli przypadków i generuje osadzanie dla opinii przypadków przy użyciu interfejsu API openAI. Przechowuje embeddingi w nowej kolumnie. Proces osadzania trwa od około 3 do 5 minut.

Aby rozpocząć proces ładowania danych, uruchom następujące polecenie z load_data katalogu:

python main.py

Oto dane wyjściowe 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!

Krok 2. Tworzenie narzędzia Postgres dla agenta

Następnie skonfiguruj narzędzia agenta sztucznej inteligencji do pobierania danych z bazy danych Postgres. Następnie użyj zestawu SDK agenta usługi Azure AI Foundry, aby połączyć agenta sztucznej inteligencji z bazą danych Postgres.

Definiowanie funkcji, która ma być wywoływana przez agenta

Zacznij od zdefiniowania funkcji, która ma być wywoływana przez agenta, opisując jego strukturę i wszelkie wymagane parametry w kodzie. Uwzględnij wszystkie definicje funkcji w jednym pliku, legal_agent_tools.py. Następnie możesz zaimportować plik do głównego skryptu.

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 case 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

Krok 3. Tworzenie i konfigurowanie agenta sztucznej inteligencji przy użyciu bazy danych Postgres

Teraz skonfiguruj agenta sztucznej inteligencji i zintegruj go z narzędziem Postgres. Plik języka Python src/simple_postgres_and_ai_agent.py służy jako centralny punkt wejścia do tworzenia i używania agenta.

Plik simple_postgres_and_ai_agent.py:

Inicjuje agenta w projekcie usługi Azure AI Foundry przy użyciu określonego modelu.
Dodaje narzędzie Postgres do wyszukiwania wektorowego w bazie danych podczas inicjowania agenta.
Konfiguruje wątek komunikacji. Ten wątek służy do wysyłania komunikatów do agenta do przetwarzania.
Przetwarza zapytanie użytkownika przy użyciu agenta i narzędzi. Agent może planować za pomocą narzędzi, aby uzyskać poprawną odpowiedź. W tym przypadku użycia agent wywołuje narzędzie Postgres na podstawie podpisu funkcji i docstringu, aby przeprowadzić wyszukiwanie wektorowe i pobrać odpowiednie dane w celu odpowiedzi na pytanie.
Wyświetla odpowiedź agenta na zapytanie użytkownika.

Znajdowanie parametrów połączenia projektu w narzędziu Azure AI Foundry

W projekcie usługi Azure AI Foundry możesz znaleźć parametry połączenia projektu ze strony przeglądu projektu. Ten ciąg służy do łączenia projektu z SDK usługi agenta Azure AI Foundry. Dodaj ten ciąg do .env pliku.

Zrzut ekranu przedstawiający stronę konfiguracji projektu.

Konfigurowanie połączenia

Dodaj te zmienne do .env pliku w katalogu głównym:

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 Azure 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/azure-ai-agent-service/src/simple_postgres_and_ai_agent.py).

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

# Initialize the 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
)

Tworzenie wątku komunikacyjnego

Ten fragment kodu pokazuje, jak utworzyć wątek agenta i komunikat, który agent przetwarza w uruchomieniu:

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

# Create a 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?"
)

Przetwarzanie żądania

Poniższy fragment kodu tworzy uruchomienie dla agenta w celu przetworzenia komunikatu, używając odpowiednich narzędzi, aby osiągnąć najlepszy wynik.

Używając narzędzi, agent może wywołać Postgres i zastosować wyszukiwanie wektorowe na zapytaniu "Wyciek wody do mieszkania z podłogi powyżej", aby pobrać dane potrzebne do najlepszego udzielenia odpowiedzi na pytanie.

from pprint import pprint

# Create and process an agent run in the 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'])

Uruchamianie agenta

Aby uruchomić agenta, uruchom następujące polecenie z src katalogu:

python simple_postgres_and_ai_agent.py

Agent generuje podobny wynik przy użyciu narzędzia Azure Database for PostgreSQL w celu uzyskania dostępu do danych przypadków zapisanych w bazie danych Postgres.

Oto fragment danych wyjściowych agenta:

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.

Krok 4. Testowanie i debugowanie za pomocą placu zabaw agenta

Po uruchomieniu agenta za pomocą SDK usługi agenta Azure AI Foundry, agent jest przechowywany w projekcie. Możesz eksperymentować z agentem na placu zabaw agenta:

W usłudze Azure AI Foundry przejdź do sekcji Agenci .
Znajdź agenta na liście i wybierz go, aby go otworzyć.
Użyj interfejsu placu zabaw, aby przetestować różne zapytania prawne.
Przetestuj zapytanie "Wyciek wody do mieszkania z piętra powyżej, Jakie są znane precedensy prawne w Waszyngtonie?" Agent wybiera odpowiednie narzędzie i pyta o oczekiwane dane wyjściowe dla tego zapytania. Użyj sample_vector_search_cases_output.json jako przykładowych danych wyjściowych.

Krok 5. Debugowanie za pomocą śledzenia usługi Azure AI Foundry

Podczas opracowywania agenta przy użyciu pakietu SDK Azure AI Foundry Agent Service można debugować agenta za pomocą śledzenia. Śledzenie umożliwia debugowanie wywołań do narzędzi takich jak Postgres i sprawdzenie, jak agent organizuje każde zadanie.

W usłudze Azure AI Foundry przejdź do pozycji Śledzenie.
Aby utworzyć nowy zasób usługi Application Insights, wybierz pozycję Utwórz nowy. Aby połączyć istniejący zasób, wybierz jeden z nich w polu Nazwa zasobu usługi Application Insights , a następnie wybierz pozycję Połącz.
Wyświetl szczegółowe ślady operacji agenta.

Dowiedz się więcej o sposobie konfigurowania śledzenia za pomocą agenta sztucznej inteligencji i bazy danych Postgres w pliku advanced_postgres_and_ai_agent_with_tracing.py w usłudze GitHub.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-06-27