Pydantic AI 向量表示 (Embeddings)

在構建現代 AI 應用（特別是 RAG - 檢索增強生成系統）時，將文字或文件轉換成一串數字構成的向量（Embeddings）是不可或缺的步驟。向量化能夠讓電腦計算兩段文字在語意上的相似度，從而在龐大的資料庫中精準搜尋出最相關的文件提供給 Agent 參考。

Pydantic AI 作為一個全方位的框架，不僅負責代理人的執行邏輯，也提供了簡潔的 API 來幫助你產生與處理 Embeddings。

什麼是 Embeddings？

如果你對這個概念還不熟悉，可以把 Embeddings 想像成一段文字的「DNA 序列」或「座標」。

意義相近的詞彙或句子，它們轉換出來的座標點會在多維度的空間中靠得非常近；而毫無關聯的句子，它們的座標點就會相隔很遠。這讓我們可以利用數學方法（如計算餘弦相似度 Cosine Similarity）來進行高效的「語意搜尋」。

產生文字的向量

在 Pydantic AI 中，你可以輕易地呼叫特定的模型來為你的字串生成 Embeddings。這通常涉及使用特定的 Embedding 類別或模型提供者的介面。

import asyncio
# 引入與 Embeddings 相關的模組 (以實際版本為準)
from pydantic_ai.embeddings import EmbeddingsClient

async def main():
    # 建立一個 Embedding 客戶端，指定使用 OpenAI 的 text-embedding-3-small 模型
    # 這與 Agent 的模型設定方式相似
    client = EmbeddingsClient('openai:text-embedding-3-small')
    
    # 準備我們要轉換的文字陣列
    texts = [
        "Pydantic AI 是一個超好用的 Python 框架。",
        "今天台北的天氣非常晴朗，適合出遊。",
        "什麼是依賴注入機制？"
    ]
    
    # 呼叫非同步方法來獲取向量
    embeddings_result = await client.embed(texts)
    
    # embeddings_result 通常會包含一個浮點數列表的陣列
    for i, text in enumerate(texts):
        # 為了排版，這裡只印出該段文字向量的前三個維度的數字
        vector = embeddings_result[i][:3]
        print(f"文字: '{text}'")
        print(f"向量前三碼: {vector}...\n")

asyncio.run(main())

在 RAG (檢索增強生成) 中的應用

雖然 Pydantic AI 本身專注於 Agent 框架，並不包含內建的向量資料庫（如 Pinecone, Qdrant 或是 Chroma），但它提供的 Embeddings 工具可以完美地融入你的 RAG 工作流中。

一個典型的 Pydantic AI RAG 流程設計如下：

  1. 資料預處理階段：使用 Pydantic AI 的 EmbeddingsClient 將你的企業內部文件或是知識庫文章轉換成向量，並儲存到你偏好的向量資料庫中。
  2. 建立 Agent 與工具：
    • 建立一個負責回答問題的 Pydantic AI Agent。
    • 寫一個 @agent.tool 工具函數，這個函數的職責是去向量資料庫搜尋資料。
  3. 執行階段：
    • 使用者問了一個問題：「公司的請假規定是什麼？」
    • Agent 決定呼叫上述搜尋工具。
    • 工具函數內部再次使用 Pydantic AI 將「公司的請假規定是什麼？」這句話轉成向量，去資料庫比對最相近的文件。
    • 工具函數將找出的文件內容回傳給 Agent。
    • Agent 根據找到的文件，給予使用者最終解答。

透過這種方式，Pydantic AI 讓你可以在同一個框架下、用一致的語法與設定風格（包含共用 API Key、Retry 機制與 Logfire 監控），同時處理複雜的語言模型邏輯與基礎的向量轉換。