text2sql — 自然言語 SQL クエリアシスタント

AI/ML
text2sql — 自然言語 SQL クエリアシスタント

text2sql — 自然言語 SQL クエリアシスタント

Harness Engineer 向けに設計された「text2sql」は、DeepAgent フレームワーク上で動作する自然言語→SQL 変換アシスタントです。Qwen‑Max をバックエンドに、スキーマ探索、只読モード（SELECT のみ許可）、LangGraph による可視化、LangSmith による実行追跡などを組み合わせ、SQL 知識がないユーザーでも安全かつトレーサブルにデータベース照会を行えます。（約300字）

https://github.com/ms-alan/text2sql

概要

このリポジトリは、DeepAgent フレームワークを核にした「Harness Engineer」向けの SQL クエリアシスタントです。日本語などの自然言語で問い合わせると、内部でスキーマを探索して適切な SQL（主に SELECT）を自動生成し、SQLite 上で実行できます。Qwen‑Max を LLM として利用し、LangGraph によるワークフロー可視化と LangSmith による実行トレースをサポート。セキュリティ面では只読モードを備え、運用環境での誤操作リスクを低減します。

GitHub

リポジトリの統計情報

  • スター数: 2
  • フォーク数: 0
  • ウォッチャー数: 2
  • コミット数: 2
  • ファイル数: 11
  • メインの言語: Python

主な特徴

  • 自然言語（中文／日本語想定）から自動で SQL を生成して実行
  • スキーマ探索機能によりデータベース構造を自動理解
  • LangGraph によるワークフロー可視化と LangSmith による実行ログ追跡
  • Qwen‑Max を LLM として利用、只読モード（SELECT のみ許可）で安全性を確保

技術的なポイント

text2sql は DeepAgent を中心に、エージェント駆動で自然言語から SQL を導出する設計が特徴です。主な処理フローは「ユーザーの自然言語入力 → エージェント（agent.py）による意図解析とスキーマ照会 → SQL 生成 → SQLite での実行 → 結果返却／可視化（LangGraph）」という流れになります。スキーマ探索では、データベースのテーブル名・カラム名・型情報を自動取得し、LLM に与えるコンテキストとして用いるため、モデルは現実のスキーマに即した SQL を生成できます。これにより、曖昧な自然言語表現からも適切な参照先や結合条件を推測しやすくなります。

安全面では「只読（read‑only）モード」を前提としており、システムは基本的に SELECT 文のみを許可する方針です。実際の実行前に生成された SQL を解析して、更新系（INSERT/UPDATE/DELETE/DROP 等）が含まれていないかチェックするガードを組み込む設計が想定されます。また、機密情報や実行権限の管理は .env.example に格納される Qwen API キーや接続情報によって行われ、運用時は環境変数で安全に扱います。

LLM レイヤーには阿里云（Alibaba Cloud）の Qwen‑Max を用いる構成で、LangChain や DeepAgents 互換のスキル／メモリモジュールを組み合わせることで、対話の文脈保持や複数ステップの推論が可能です。LangSmith によるトレーシングを有効にすることで、生成されたプロンプトや中間推論、最終 SQL の履歴を可視化・デバッグでき、運用時の説明性（explainability）や品質改善に寄与します。さらに、LangGraph を用いたワークフロー可視化により、エージェントの意思決定パスやデータフローを図として確認できます。

拡張性としては、他の DB（Postgres/MySQL 等）や別の LLM（OpenAI、Mistral 等）への差し替えが比較的容易で、agent.py や AGENTS.md に定義されたスキル群を追加・修正することでカスタムのドメイン知識を導入できます。運用上の注意点としては、LLM の誤生成（hallucination）対策やスキーマ理解の精度向上のために、プロンプト設計とスキーマ記述の最適化が重要です。

プロジェクトの構成

主要なファイルとディレクトリ：

  • .env.example: file
  • .gitignore: file
  • AGENTS.md: file
  • README.md: file
  • agent.py: file

…他 6 ファイル

（agent.py がエージェント本体のエントリ、AGENTS.md にエージェント設計やスキルの説明、.env.example に Qwen API キー等の環境変数サンプルが含まれている想定です）

まとめ

LLM とエージェント設計を組み合わせた、安全で追跡可能な自然言語→SQL ツールのシンプルな実装例です。

リポジトリ情報：

  • 名前: text2sql
  • 説明: # Harness Engineer - SQL Query Assistant 🚀 基于 DeepAgent 框架的智能 SQL 查询助手，专为 Harness Engineer 打造。 核心能力： - 💬 自然语言 → SQL 自动转换 - 🔍 智能 Schema 探索 - 📊 LangSmith 完整追踪 - 阿里云 Qwen-Max 驱动 - 🔒 只读安全模式 技术栈： DeepAgents | LangChain | LangGraph | Qwen-Max | SQLite
  • スター数: 2
  • 言語: Python
  • URL: https://github.com/ms-alan/text2sql
  • オーナー: ms-alan
  • アバター: https://avatars.githubusercontent.com/u/1472110?v=4

README抜粋（主要ポイント）：

  • 自然言語での問い合わせから自動で SQL を生成
  • スキーマ探索、LangGraph による可視化、LangSmith によるトレース
  • Qwen‑Max を LLM として使用、只読モードで安全性確保
  • DeepAgent ベースでスキルやメモリを組み合わせ可能

参考として、導入時は .env.example を基に API キー等を設定し、まずはローカルの SQLite 接続で動作確認を行うことを推奨します。