Azure Database untuk PostgreSQL memiliki agen AI

2025-06-27

Agen AI mengubah cara aplikasi berinteraksi dengan data dengan menggabungkan model bahasa besar (LLM) dengan alat dan database eksternal. Agen memungkinkan otomatisasi alur kerja yang kompleks, meningkatkan akurasi pengambilan informasi, dan memfasilitasi antarmuka bahasa alami ke database.

Artikel ini membahas cara membuat agen AI cerdas yang dapat mencari dan menganalisis data Anda di Azure Database for PostgreSQL. Ini berjalan melalui penyiapan, implementasi, dan pengujian dengan menggunakan asisten peneliti hukum sebagai contoh.

Apa itu agen AI?

Agen AI melampaui chatbot sederhana dengan menggabungkan LLM dengan alat dan database eksternal. Tidak seperti LLM yang berdiri sendiri atau sistem pembuatan berbantuan pengambilan standar (RAG), agens AI dapat:

Rencana: Memecah tugas kompleks menjadi langkah-langkah yang lebih kecil dan berurutan.
Gunakan alat: Gunakan API, eksekusi kode, dan sistem pencarian untuk mengumpulkan informasi atau melakukan tindakan.
Perceive: Memahami dan memproses input dari berbagai sumber data.
Ingat: Simpan dan ingat interaksi sebelumnya untuk pengambilan keputusan yang lebih baik.

Dengan menyambungkan agen AI ke database seperti Azure Database for PostgreSQL, agen dapat memberikan respons yang lebih akurat dan sadar konteks berdasarkan data Anda. Agen AI melampaui batas percakapan manusia biasa untuk melakukan tugas berdasarkan bahasa natural. Tugas-tugas ini secara tradisional memerlukan logika berkode. Namun, agen dapat merencanakan tugas yang diperlukan untuk dijalankan berdasarkan konteks yang disediakan pengguna.

Implementasi agen AI

Menerapkan agen AI dengan Azure Database for PostgreSQL melibatkan integrasi kemampuan AI tingkat lanjut dengan fungsionalitas database yang kuat untuk membuat sistem yang cerdas dan sadar konteks. Dengan menggunakan alat seperti pencarian vektor, penyematan, dan Azure AI Foundry Agent Service, pengembang dapat membangun agen yang memahami kueri bahasa alami, mengambil data yang relevan, dan memberikan wawasan yang dapat ditindaklanjuti.

Bagian berikut menguraikan proses langkah demi langkah untuk menyiapkan, mengonfigurasi, dan menyebarkan agen AI. Proses ini memungkinkan interaksi yang mulus antara model AI dan database PostgreSQL Anda.

Kerangka kerja

Berbagai kerangka kerja dan alat dapat memfasilitasi pengembangan dan penyebaran agen AI. Semua kerangka kerja ini mendukung penggunaan Azure Database for PostgreSQL sebagai alat:

Contoh implementasi

Contoh artikel ini menggunakan Azure AI Foundry Agent Service untuk perencanaan agen, penggunaan alat, dan persepsi. Ini menggunakan Azure Database for PostgreSQL sebagai alat untuk database vektor dan kemampuan pencarian semantik.

Bagian berikut akan memandu Anda dalam membangun agen AI yang membantu tim pengacara meneliti kasus yang relevan untuk mendukung klien mereka di Negara Bagian Washington. Agen:

Menerima kueri bahasa alami tentang situasi hukum.
Menggunakan pencarian vektor di Azure Database for PostgreSQL untuk menemukan preseden kasus yang relevan.
Menganalisis dan meringkas temuan dalam format bermanfaat untuk profesional hukum.

Prasyarat

Mengaktifkan dan mengonfigurasiazure_ai dan pg_vector ekstensi.
Buat proyek Azure AI Foundry.
Menyebarkan modelgpt-4o-mini dan text-embedding-small.
Instal Visual Studio Code.
Pasang ekstensi Python .
Instal Python 3.11.x.
Instal Azure CLI (versi terbaru).

Nota

Anda memerlukan kunci dan endpoint dari model yang telah Anda terapkan untuk agen.

Memulai Langkah Pertama

Semua himpunan data kode dan sampel tersedia di repositori GitHub ini.

Langkah 1: Menyiapkan pencarian vektor di Azure Database for PostgreSQL

Pertama, siapkan database Anda untuk menyimpan dan mencari data kasus hukum dengan menggunakan penyematan vektor.

Menyiapkan lingkungan kerja

Jika Anda menggunakan macOS dan Bash, jalankan perintah ini:

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

Jika Anda menggunakan Windows dan PowerShell, jalankan perintah ini:

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

Jika Anda menggunakan Windows dan cmd.exe, jalankan perintah ini:

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

Mengonfigurasi variabel lingkungan

Buat .env file dengan kredensial Anda:

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

Memuat dokumen dan vektor

File Python load_data/main.py berfungsi sebagai titik masuk pusat untuk memuat data ke Azure Database for PostgreSQL. Kode memproses data untuk kasus sampel, termasuk informasi tentang kasus di Washington.

File main.py:

Membuat ekstensi yang diperlukan, menyiapkan pengaturan OPENAI API, dan mengelola tabel database dengan menghilangkan yang sudah ada dan membuat yang baru untuk menyimpan data kasus.
Membaca data dari file CSV dan menyisipkannya ke dalam tabel sementara, lalu memproses dan mentransfernya ke dalam tabel kasus utama.
Menambahkan kolom baru untuk penyematan dalam tabel kasus dan menghasilkan penyematan untuk pendapat kasus dengan menggunakan API OpenAI. Menyimpan embedding di kolom baru. Proses penyematan membutuhkan waktu sekitar 3 hingga 5 menit.

Untuk memulai proses pemuatan data, jalankan perintah berikut dari load_data direktori:

python main.py

Berikut adalah output dari 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!

Langkah 2: Membuat alat Postgres untuk agen

Selanjutnya, konfigurasikan alat agen AI untuk mengambil data dari Postgres. Kemudian gunakan Azure AI Foundry Agent Service SDK untuk menyambungkan agen AI Anda ke database Postgres.

Tentukan fungsi untuk dipanggil agen Anda

Mulailah dengan mendefinisikan fungsi untuk dipanggil agen Anda dengan menjelaskan strukturnya dan parameter yang diperlukan dalam docstring. Sertakan semua definisi fungsi Anda dalam satu file, legal_agent_tools.py. Anda kemudian dapat mengimpor file ke skrip utama Anda.

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

Langkah 3: Membuat dan mengonfigurasi agen AI dengan Postgres

Sekarang, siapkan agen AI dan integrasikan dengan alat Postgres. File Python src/simple_postgres_and_ai_agent.py berfungsi sebagai titik masuk pusat untuk membuat dan menggunakan agen Anda.

File simple_postgres_and_ai_agent.py:

Menginisialisasi agen dalam proyek Azure AI Foundry Anda dengan model tertentu.
Menambahkan alat Postgres untuk pencarian vektor di database Anda, selama inisialisasi agen.
Menyiapkan utas komunikasi. Thread ini digunakan untuk mengirim pesan ke agen untuk diproses.
Memproses kueri pengguna dengan menggunakan agen dan alat. Agen dapat merencanakan dengan alat untuk mendapatkan jawaban yang benar. Dalam kasus penggunaan ini, agen memanggil alat Postgres berdasarkan tanda tangan fungsi dan docstring untuk melakukan pencarian vektor dan mengambil data yang relevan untuk menjawab pertanyaan.
Menampilkan respons agen terhadap kueri pengguna.

Menemukan string koneksi proyek di Azure AI Foundry

Di proyek Azure AI Foundry, Anda menemukan string koneksi proyek dari halaman gambaran umum proyek. Anda menggunakan string ini untuk menyambungkan proyek ke Azure AI Foundry Agent Service SDK. Tambahkan string ini ke .env file.

Cuplikan layar yang memperlihatkan halaman penyiapan proyek.

Menyiapkan koneksi

Tambahkan variabel ini ke file Anda .env di direktori akar:

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/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
)

Membuat utas komunikasi

Cuplikan kode ini menunjukkan cara membuat thread agen dan pesan, yang diproses oleh agen dalam proses run.

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

Memproses permintaan

Cuplikan kode berikut menciptakan sebuah run bagi agen untuk memproses pesan dan menggunakan tools yang tepat untuk memberikan hasil terbaik.

Dengan menggunakan alat, agen dapat memanggil Postgres dan melakukan pencarian vektor pada kueri "Air yang bocor ke apartemen dari lantai di atas" untuk mengambil data yang dibutuhkan guna menjawab pertanyaan tersebut dengan baik.

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'])

Jalankan program agen

Untuk menjalankan agen, jalankan perintah berikut dari src direktori:

python simple_postgres_and_ai_agent.py

Agen menghasilkan hasil yang sama dengan menggunakan alat Azure Database for PostgreSQL untuk mengakses data kasus yang disimpan dalam database Postgres.

Berikut adalah cuplikan output dari agen:

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.

Langkah 4: Uji dan debug dengan taman bermain agen

Setelah Anda menjalankan agen dengan menggunakan Azure AI Foundry Agent Service SDK, agen disimpan dalam proyek Anda. Anda dapat bereksperimen dengan agen di taman bermain agen:

Di Azure AI Foundry, buka bagian Agen .
Temukan agen Anda dalam daftar dan pilih untuk membukanya.
Gunakan antarmuka taman bermain untuk menguji berbagai kueri hukum.
Uji kueri "Air bocor ke apartemen dari lantai di atas, Apa preseden hukum yang menonjol di Washington?" Agen memilih alat yang tepat untuk digunakan dan meminta output yang diharapkan untuk kueri tersebut. Gunakan sample_vector_search_cases_output.json sebagai output sampel.

Langkah 5: Debug dengan pelacakan Azure AI Foundry

Saat mengembangkan agen dengan menggunakan Azure AI Foundry Agent Service SDK, Anda dapat melakukan debug agen dengan pelacakan. Pelacakan memungkinkan Anda untuk men-debug panggilan ke alat seperti Postgres dan melihat bagaimana agen mengatur setiap tugas.

Di Azure AI Foundry, buka Pelacakan.
Untuk membuat sumber daya Application Insights baru, pilih Buat baru. Untuk menyambungkan sumber daya yang sudah ada, pilih sumber daya di kotak nama sumber daya Application Insights , lalu pilih Sambungkan.
Lihat jejak terperinci dari operasi agen Anda.

Pelajari selengkapnya tentang cara menyiapkan pelacakan dengan agen AI dan Postgres dalam file advanced_postgres_and_ai_agent_with_tracing.py di GitHub.

Bagikan melalui