텍스트-to-SQL 평가 퀵스타트

텍스트-to-SQL 평가 퀵스타트 (Text-to-SQL Evaluation Quickstart)

text2sql 템플릿은 SQL 실행 결과를 비교해서 텍스트-to-SQL 시스템을 평가해요. 프로젝트 생성부터 실행 정확도 기반 평가까지 진행할 수 있어요.

출처: 문서

본문

text2sql 템플릿은 SQL 실행 결과를 비교해서 텍스트-to-SQL 시스템을 평가해요.

프로젝트 만들기

ragas quickstart text2sql
cd text2sql

의존성 설치

uv sync

API 키 설정

export OPENAI_API_KEY="your-openai-key"

평가 실행

uv run python evals.py

프로젝트 구조

text2sql/
├── README.md              # Project documentation
├── pyproject.toml         # Project configuration
├── text2sql_agent.py      # Text-to-SQL agent
├── db_utils.py            # Database utilities
├── evals.py               # Evaluation workflow
├── prompt.txt             # Base prompt template
├── prompt_v2.txt          # Improved prompt v2
├── prompt_v3.txt          # Improved prompt v3
├── __init__.py            # Python package marker
└── evals/
    ├── datasets/
    │   └── booksql_sample.csv  # Sample book database queries
    ├── experiments/       # Evaluation results
    └── logs/              # Execution logs

무엇을 평가하나

템플릿은 텍스트-to-SQL 생성을 평가해요.

  • Agent: 자연어를 SQL 쿼리로 변환
  • Database: 저자, 제목, 장르가 있는 샘플 도서 데이터베이스
  • Test Cases: 자연어 질문 → 기대 SQL 쿼리
  • Metric: datacompy로 쿼리 결과를 비교하는 실행 정확도

코드 이해하기

에이전트 (text2sql_agent.py)

자연어를 SQL로 변환해요.

from text2sql_agent import Text2SQLAgent

agent = Text2SQLAgent(client=openai_client)
sql = await agent.generate_sql("Find all books by Jane Austen")

평가 (evals.py)

실행 결과를 비교해요.

@discrete_metric(name="execution_accuracy", allowed_values=["correct", "incorrect"])
def execution_accuracy(expected_sql: str, predicted_success: bool, predicted_result):
    # 두 SQL을 실행하고 datacompy로 결과 비교
    # 결과가 일치하면 "correct", 아니면 "incorrect" 반환

테스트 데이터

템플릿은 도서 데이터베이스에 대한 샘플 질문과 기대 SQL 쿼리가 있는 evals/datasets/booksql_sample.csv를 포함해요.

커스터마이즈

자신만의 데이터베이스 사용

db_utils.py를 업데이트해서 자신의 데이터베이스에 연결해요.

def get_db_connection():
    return sqlite3.connect("your_database.db")

다른 프롬프트 시도

템플릿은 prompt.txt, prompt_v2.txt, prompt_v3.txt에 세 가지 프롬프트 버전을 포함해요. 각각 테스트해서 어떤 것이 가장 잘 작동하는지 확인해요.

더 알아보기 (Learn more)