# 策展 · X (Twitter) 🔥🔥🔥

> 作者：LangChain OSS (@LangChain_OSS) · 平台：X (Twitter) · 日期：2026-04-25

> 原始來源：https://x.com/LangChain_OSS/status/2048069834605539771

## 中文摘要

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 sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'` 列出如 battle、ship、singer 等 80 個表。
- 檢查潛在相關表，如 `PRAGMA table_info('singer')` 發現無 Net_Worth 欄位，轉而檢查 `singer_solo`，確認有 `Net_Worth_Millions` 欄位。
- 最終生成正確查詢 `SELECT Name FROM singer_solo ORDER BY Net_Worth_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 不全載入文件，而是見標題清單與 `lookup_example` 工具，需時如 revenue 相關查詢時呼叫 `lookup_example("net revenue")` 取用完整內容。
- 範例：Net revenue = gross revenue minus refunds，使用 INNER JOIN orders 和 payments，指定 `orders.amt_ttl` 與 `payments` 中 `is_refund = 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",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

- 工具：`analyze_traces` 讀取未處理 trace、schema 與現有情境，LLM 生成改善寫入文件；`get_summary` 提供統計（總 trace、成功率、未讀數、情境數）。
- 循環：執行查詢 → trace 累積 → `analyze_traces` → 情境改善 → 未來查詢取用，提升表現。例如 Spider 從 96% 到 100%，MCP 識別 LEFT vs INNER JOIN 錯誤並生成修正情境。

此回饋循環讓系統持續進化，無需人工介入。

**底層架構與 Deep Agents**

建基於 LangChain 的 [Deep Agents](https://github.com/langchain-ai/deepagents)，最小 middleware 堆疊：

- 自動上下文壓縮：總結舊工具呼叫，避免長任務 context 過載。
- Anthropic prompt caching：降低 API 成本。
- 停用預設 middleware（如檔案系統工具、子 Agent、todo 清單），僅暴露 text2sql 專屬工具（`execute_sql` + `lookup_example`）。

架構目錄：
```
text2sql/
├── core.py          # TextSQL — public API
├── generate.py      # SQLGenerator — builds the agent, parses results
├── connection.py    # Database — SQLAlchemy wrapper
├── tools.py         # execute_sql + lookup_example (LangChain tools)
├── dialects.py      # Per-dialect schema exploration guides
├── examples.py      # ExampleStore — loads scenario markdown
├── tracing.py       # Tracer — captures full agentic loop
├── analyze.py       # AnalysisEngine — deterministic trace analysis
├── models.py        # Pydantic models for analysis reports
└── cli.py           # Click CLI
```

**開源與未來展望**

MIT 授權，GitHub 連結：https://github.com/Text2SqlAgent/text2sql-framework。此 SDK 彰顯 Agentic 程式開發趨勢轉變：從靜態 RAG/semantic layer 轉向動態自主探索，隨著前沿模型支援千次工具呼叫，text-to-SQL 系統將更簡潔強大，移除多餘 guardrail 即獲能力提升，MCP 回饋循環更確保持續優化，Spider 100% 成績即為鐵證。

## 標籤

Agent, LLM, SDK, Benchmark, 開源專案, LangChain