mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-04-09 12:38:14 +00:00
147 lines
6.1 KiB
Plaintext
147 lines
6.1 KiB
Plaintext
---
|
|
title: NL2SQL 도구
|
|
description: NL2SQLTool은 자연어를 SQL 쿼리로 변환하도록 설계되었습니다.
|
|
icon: language
|
|
mode: "wide"
|
|
---
|
|
|
|
## 개요
|
|
|
|
이 도구는 자연어를 SQL 쿼리로 변환하는 데 사용됩니다. 에이전트에 전달되면 쿼리를 생성하고 이를 사용하여 데이터베이스와 상호작용합니다.
|
|
|
|
이를 통해 에이전트가 데이터베이스에 접근하여 목표에 따라 정보를 가져오고, 해당 정보를 사용해 응답, 보고서 또는 기타 출력물을 생성하는 다양한 워크플로우가 가능해집니다. 또한 에이전트가 자신의 목표에 맞춰 데이터베이스를 업데이트할 수 있는 기능도 제공합니다.
|
|
|
|
**주의**: 도구는 기본적으로 읽기 전용(SELECT/SHOW/DESCRIBE/EXPLAIN만 허용)으로 동작합니다. 쓰기 작업을 수행하려면 `allow_dml=True` 매개변수 또는 `CREWAI_NL2SQL_ALLOW_DML=true` 환경 변수가 필요합니다. 쓰기 접근이 활성화된 경우, 가능하면 권한이 제한된 데이터베이스 사용자나 읽기 복제본을 사용하십시오.
|
|
|
|
## 읽기 전용 모드 및 DML 구성
|
|
|
|
`NL2SQLTool`은 기본적으로 **읽기 전용 모드**로 동작합니다. 추가 구성 없이 허용되는 구문 유형은 다음과 같습니다:
|
|
|
|
- `SELECT`
|
|
- `SHOW`
|
|
- `DESCRIBE`
|
|
- `EXPLAIN`
|
|
|
|
DML을 명시적으로 활성화하지 않으면 쓰기 작업(`INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `TRUNCATE` 등)을 실행하려고 할 때 오류가 발생합니다.
|
|
|
|
읽기 전용 모드에서는 세미콜론이 포함된 다중 구문 쿼리(예: `SELECT 1; DROP TABLE users`)도 인젝션 공격을 방지하기 위해 차단됩니다.
|
|
|
|
### 쓰기 작업 활성화
|
|
|
|
DML(데이터 조작 언어)을 활성화하는 방법은 두 가지입니다:
|
|
|
|
**옵션 1 — 생성자 매개변수:**
|
|
|
|
```python
|
|
from crewai_tools import NL2SQLTool
|
|
|
|
nl2sql = NL2SQLTool(
|
|
db_uri="postgresql://example@localhost:5432/test_db",
|
|
allow_dml=True,
|
|
)
|
|
```
|
|
|
|
**옵션 2 — 환경 변수:**
|
|
|
|
```bash
|
|
CREWAI_NL2SQL_ALLOW_DML=true
|
|
```
|
|
|
|
```python
|
|
from crewai_tools import NL2SQLTool
|
|
|
|
# 환경 변수를 통해 DML 활성화
|
|
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
|
|
```
|
|
|
|
### 사용 예시
|
|
|
|
**읽기 전용(기본값) — 분석 및 보고 워크로드에 안전:**
|
|
|
|
```python
|
|
from crewai_tools import NL2SQLTool
|
|
|
|
# SELECT/SHOW/DESCRIBE/EXPLAIN만 허용
|
|
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
|
|
```
|
|
|
|
**DML 활성화 — 쓰기 워크로드에 필요:**
|
|
|
|
```python
|
|
from crewai_tools import NL2SQLTool
|
|
|
|
# INSERT, UPDATE, DELETE, DROP 등이 허용됨
|
|
nl2sql = NL2SQLTool(
|
|
db_uri="postgresql://example@localhost:5432/test_db",
|
|
allow_dml=True,
|
|
)
|
|
```
|
|
|
|
<Warning>
|
|
DML을 활성화하면 에이전트가 데이터를 수정하거나 삭제할 수 있습니다. 사용 사례에서 명시적으로 쓰기 접근이 필요한 경우에만 활성화하고, 데이터베이스 자격 증명이 최소 필요 권한으로 제한되어 있는지 확인하십시오.
|
|
</Warning>
|
|
|
|
## 요구 사항
|
|
|
|
- SqlAlchemy
|
|
- 모든 DB 호환 라이브러리(예: psycopg2, mysql-connector-python)
|
|
|
|
## 설치
|
|
|
|
crewai_tools 패키지 설치
|
|
|
|
```shell
|
|
pip install 'crewai[tools]'
|
|
```
|
|
|
|
## 사용법
|
|
|
|
NL2SQLTool을 사용하려면 데이터베이스 URI를 도구에 전달해야 합니다. URI는 `dialect+driver://username:password@host:port/database` 형식이어야 합니다.
|
|
|
|
|
|
```python Code
|
|
from crewai_tools import NL2SQLTool
|
|
|
|
# psycopg2 was installed to run this example with PostgreSQL
|
|
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
|
|
|
|
@agent
|
|
def researcher(self) -> Agent:
|
|
return Agent(
|
|
config=self.agents_config["researcher"],
|
|
allow_delegation=False,
|
|
tools=[nl2sql]
|
|
)
|
|
```
|
|
|
|
## 예시
|
|
|
|
주요 작업 목표는 다음과 같았습니다:
|
|
|
|
"각 도시에 대해 월별 평균, 최대, 최소 매출을 조회하되, 사용자 수가 1명 초과인 도시만 포함하세요. 또한 각 도시의 사용자 수를 세고, 평균 월 매출을 기준으로 내림차순 정렬하십시오."
|
|
|
|
그래서 에이전트는 DB에서 정보를 얻으려고 시도했고, 처음 시도는 잘못되었으므로 에이전트가 다시 시도하여 올바른 정보를 얻은 후 다음 에이전트로 전달합니다.
|
|
|
|
|
|
|
|
|
|
두 번째 작업 목표는 다음과 같았습니다:
|
|
|
|
"데이터를 검토하고 상세한 보고서를 작성한 다음, 제공된 데이터를 기반으로 필드를 갖는 테이블을 데이터베이스에 생성하세요. 각 도시에 대해 월별 평균, 최대, 최소 매출 정보를 포함하되, 사용자 수가 1명 초과인 도시만 포함시키세요. 또한 각 도시의 사용자 수를 세고, 평균 월 매출을 기준으로 내림차순 정렬하십시오."
|
|
|
|
이제 상황이 흥미로워집니다. 에이전트는 테이블을 생성할 SQL 쿼리뿐만 아니라 데이터를 테이블에 삽입하는 쿼리도 생성합니다. 그리고 마지막에는 데이터베이스에 있던 것과 정확히 일치하는 최종 보고서도 반환합니다.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
이것은 NL2SQLTool이 데이터베이스와 상호작용하고, 데이터베이스의 데이터를 기반으로 보고서를 생성하는 데 어떻게 사용될 수 있는지에 대한 간단한 예시입니다.
|
|
|
|
이 도구는 에이전트의 논리와 데이터베이스와 상호작용하는 방식에 대해 무한한 가능성을 제공합니다.
|
|
|
|
```md
|
|
DB -> Agent -> ... -> Agent -> DB
|
|
```
|