@LangChain_OSS：LangChain Community Spotlight：text2sql 實現 Spider 基準 100% 準確率。 text2sql 是一個基於 …

LangChain Community Spotlight：text2sql 實現 Spider 基準 100% 準確率。 text2sql 是一個基於 LangChain Deep Agents 的 Agentic text-to-SQL SDK，能自主探索 schema、撰寫查詢並自我修正，無需 RAG 或預計算 schema，即在 Spider 基準上達成 100% 準確率。透過單一 execute_sql 工具，前沿模型可進行數百次迭代工具呼叫，讓 Agent 在真實資料上測試並修正，展現 LLM 遞迴工具使用能力的躍進。 運作原理 Agent 連接單一資料庫，自主探索 schema 並生成 SQL，所有步驟在同一循環中進行，而非分離管道階段。 先查詢所有資料表清單，例如在包含 80 個資料表的資料庫中，使用 SELECT name FROM sqlitemaster WHERE type='table' AND name NOT LIKE 'sqlite%' 列出如 battle、ship、singer 等 80 個表。 檢查潛在相關表，如 PRAGMA tableinfo('singer') 發現無 NetWorth 欄位，轉而檢查 singersolo，確認有 NetWorth_Millions 欄位。 最終生成正確查詢 SELECT Name FROM singersolo ORDER BY NetWorth_Millions ASC，輸出如 Abigail Johnson、Susanne Klatten 等結果。 若選錯表、查詢出錯或輸出不對，Agent 會讀取錯誤訊息或重新思考，僅需 4 次工具呼叫，全程自主。 此設計強調移除不必要的 guardrail，讓 LLM 能力盡數發揮，隨著模型進步，需持續重構 harness 以最小約束。 基準測試表現 在 Spider 基準（10,000+ 問題跨 200 個資料庫）上，將 20 個 dev-set 資料庫合併成單一 80 表資料庫，隨機選 20 題（每資料庫一題）進行 zero-shot 測試。 初始 19/20（95%），單一失敗為模糊問題「What is maximum and minimum death toll caused each time?」，Agent 誤解為 per-battle 結果而非全域聚合。 加入一行情境說明「each time」指整體後，Agent 透過 lookup_example 工具取用指導，達成 20/20（100%）。 此結果無需範例，證明 Agent 在複雜 schema 中自主導航能力。 安裝與快速入門 透過 pip 安裝，支援 Anthropic 或 OpenAI。 `python from text2sql import TextSQL engine = TextSQL("postgresql://user:pass@localhost/mydb", trace_file="traces.jsonl") result = engine.ask("Which customers have spent more than $10K this year?") print(result.sql) verified SQL print(result.data) [{'name': 'Acme Corp', 'total': 14302.50}, ...] ` 控制回傳列數：engine.ask("All customers in New York", max_rows=50)。 CLI 模式：text2sql ask "sqlite:///mydb.db" 進入互動，或 text2sql query "sqlite:///mydb.db" "How many orders per month?" 單次查詢。 LLM 提供者與資料庫支援 推薦 Anthropic，但相容多供應商。 Anthropic：model="anthropic:claude-sonnet-4-6"。 OpenAI：model="openai:gpt-4o"。 支援任何 SQLAlchemy 驅動資料庫，Agent 自動偵測方言並調整探索策略： PostgreSQL/MySQL/Snowflake：使用 information_schema。 SQLite：使用 PRAGMA。 SQL Server：使用 sys.tables。 範例連線： `python TextSQL("postgresql://user:pass@localhost/mydb") TextSQL("mysql+pymysql://user:pass@localhost/mydb") TextSQL("sqlite:///mydb.db") TextSQL("snowflake://user:pass@account/db/schema") ` 情境與回饋循環 預設僅需連線字串即可運作，但真實資料庫常有專有名詞、業務邏輯，透過 scenarios.md Markdown 文件提供領域知識，每 heading 記錄規則、欄位翻譯、JOIN 路徑或修正指導。 Agent 不全載入文件，而是見標題清單與 lookupexample 工具，需時如 revenue 相關查詢時呼叫 lookupexample("net revenue") 取用完整內容。 範例：Net revenue = gross revenue minus refunds，使用 INNER JOIN orders 和 payments，指定 orders.amtttl 與 payments 中 isrefund = 1 的正確 SQL。 使用方式： `python engine = TextSQL("postgresql://localhost/mydb", examples="scenarios.md", trace_file="traces.jsonl") ` MCP 自動建構情境 無需手寫情境，SDK 記錄完整 trace（探索表、嘗試 SQL、錯誤與修正），MCP 伺服器分析 trace 並自動寫入 scenarios.md。 安裝：pip install text2sql-mcp。 配置 .mcp.json： `json { "mcpServers": { "text2sql": { "command": "text2sql-mcp", "env": { "TEXT2SQL_DB": "sqlite:///mydb.db", "TEXT2SQL_TRACES": "traces.jsonl", "TEXT2SQL_EXAMPLES": "scenarios.md", "ANTHROPICAPIKEY": "sk-ant-..." } } } } ` 工具：analyzetraces 讀取未處理 trace、schema 與現有情境，LLM 生成改善寫入文件；getsummary 提供統計（總 trace、成功率、未讀數、情境數）。 循環：執行查詢 → trace 累積 → analyze_traces → 情境改善 → 未來查詢取用，提升表現。例如 Spider 從 96% 到 100%，MCP 識別 LEFT vs INNER JOIN 錯誤並生成修正情境。 此回饋循環讓系統持續進化，無需人工介入。 底層架構與 Deep Agents 建基於 LangChain 的 Deep Agents，最小 middleware 堆疊： 自動上下文壓縮：總結舊工具呼叫，避免長任務 context 過載。 Anthropic prompt caching：降低 API 成本。 停用預設 mi…