Python으로 자연어-SQL API 구축하기

대부분의 데이터 관련 질문은 평이한 영어로 시작됩니다.

"어떤 고객이 가장 많은 지출을 했나요?"

"대기 중인 주문은 몇 개인가요?"

"지난달에 어떤 제품이 매출을 발생시켰나요?"

누군가 이러한 질문들을 SQL로 변환할 수 있지만, 이는 보통 개발자, 분석가 또는 대시보드 업데이트를 기다려야 함을 의미합니다.

이 Python 예제는 Telnyx AI Inference를 사용하여 작은 자연어-SQL (Natural Language to SQL) API를 구축하는 방법을 보여줍니다.

코드: https://github.com/team-telnyx/telnyx-code-examples/tree/main/sql-natural-language-python

기능

Flask 앱은 다음을 노출합니다:

POST /query
POST /query/sample
POST /validate
...

POST /query는 자연어 질문, SQL 방언 (SQL dialect), 그리고 스키마 DDL을 수락합니다. 생성된 SQL, 설명, 사용된 테이블 및 메타데이터가 포함된 구조화된 JSON을 반환합니다.

POST /query/sample은 번들로 제공되는 SQLite 샘플 데이터셋을 사용하여, 운영 데이터베이스에 연결하지 않고도 질문을 던지고 실제 행(row)이 반환되는 것을 확인할 수 있습니다.

POST /validate는 샘플 데이터셋을 대상으로 SQL 문자열을 드라이 런 (dry-run) 합니다.

검증(Validation)이 중요한 이유

자연어-SQL (Natural Language to SQL)에는 가드레일 (guardrails)이 필요합니다.

이 예제는 모델에 읽기 전용 (read-only) SQL을 요청한 다음, 실행 전에 생성된 쿼리를 확인합니다. 검증 계층 (validation layer)은 다중 문 (multiple statements), 주석 (comments), 그리고 쓰기 지향적인 SQL 키워드를 거부합니다.

이를 통해 예제가 다음과 같은 유용한 워크플로우 (workflow)에 집중할 수 있게 합니다:

질문하기
스키마 컨텍스트 (schema context) 포함하기
쿼리 생성하기
쿼리 검증하기
구조화된 결과 반환하기

모델은 언어 번역을 수행합니다. 앱은 여전히 안전 점검을 담당합니다.

실행하기

예제 리포지토리 (repo)를 클론 (clone) 하세요:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/sql-natural-language-python

.env 파일을 생성하세요:

cp .env.example .env

Telnyx API 키를 추가하세요:

TELNYX_API_KEY=your_telnyx_api_key
AI_MODEL=moonshotai/Kimi-K2.6
HOST=127.0.0.1

설치 및 시작:

설치 및 실행:

pip install -r requirements.txt
python app.py

샘플 데이터셋에 대한 질문하기:

curl -X POST http://localhost:5000/query/sample \
  -H "Content-Type: application/json" \
  -d '{"question": "Show me the top 3 customers by total order revenue"}' | python3 -m json.tool

쿼리 유효성 검사하기:

curl -X POST http://localhost:5000/validate \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM orders WHERE total > 100"}' | python3 -m json.tool