> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL용 vsql_ai 확장 기능

> vsql_ai 확장 기능은 SQL에서 Claude, Gemini, OpenAI, 로컬 Ollama 모델을 호출하여 쿼리 안에서 프롬프트 응답과 임베딩 벡터를 반환합니다.

대부분의 데이터베이스 AI 작업은 같은 형태를 따릅니다: 행을 읽고, 모델에 보내고,
기다리고, 답을 다시 씁니다. `vsql_ai`는 SQL에서 모델을 직접 호출하여 그 중간
과정을 없앱니다. 함수 두 개로 충분합니다. 하나는 프롬프트용, 하나는 임베딩용입니다.
프롬프트 함수는 Anthropic Claude, Google Gemini, OpenAI 또는 Ollama로 로컬에서
실행하는 모델과 함께 동작합니다. 임베딩 함수는 Anthropic을 제외한 모든 제공자와
함께 동작합니다.

| | |
| - | - |
| **관리자** | VillageSQL |
| **소스 및 전체 문서** | [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) |
| **라이선스** | GPL-2.0 |

## 설치

설치 스크립트, Docker 이미지 또는 릴리스 tarball로 VillageSQL을 설치했다면
`vsql_ai.veb`는 이미 서버의 `lib/veb/` 디렉터리에 있습니다. 문 하나로 서버에
설치하세요:

```sql theme={null}
INSTALL EXTENSION vsql_ai;
```

설치되었는지 확인합니다:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_ai';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_ai        |
+----------------+
```

직접 빌드하려면 [저장소](https://github.com/villagesql/vsql-ai)의 빌드
지침을 따르세요.

## 추가되는 기능

| 함수 | 반환값 | 설명 |
| - | - | - |
| `ai_prompt(provider, model, api_key, prompt)` | text | 프롬프트를 보내고 모델의 응답을 반환 |
| `ai_embedding(provider, model, api_key, text)` | text | 임베딩 벡터를 JSON 배열로 반환 |

`provider`는 `anthropic`, `google`, `openai` 또는 `local`입니다. 로컬 모델은
Ollama를 통해 실행되며 빈 API 키를 받습니다. `ai_embedding`은 Google, OpenAI,
로컬 모델을 지원합니다.

## 예제

로컬 모델에 질문합니다:

```sql theme={null}
SELECT ai_prompt('local', 'llama3.2', '', 'Reply with exactly one word: the capital of France.') AS answer;
```

```
+--------+
| answer |
+--------+
| Paris. |
+--------+
```

모델은 자기 나름의 표현으로 답하므로, 실제 응답은 이것과 다를 수 있습니다.

텍스트를 벡터로 바꾸고 그 차원 수를 확인합니다:

```sql theme={null}
SELECT JSON_LENGTH(ai_embedding('local', 'nomic-embed-text', '', 'Machine learning')) AS dimensions;
```

```
+------------+
| dimensions |
+------------+
|        768 |
+------------+
```

호스팅 제공자는 키와 함께 같은 호출을 받습니다:

```sql theme={null}
SET @api_key = '...';
SELECT ai_prompt('anthropic', 'claude-opus-5', @api_key, 'Hello!');
```

> [!NOTE]
>
> VillageSQL 0.0.6 이하에서는 결과가 binary 문자 집합을 가지며, 두 가지 결과가
> 따릅니다. JSON 함수나 `JSON` 열이 이를 거부하므로, 위의 임베딩 예제는 해당
> 버전에서
> `ERROR 3144 (22032): Cannot create a JSON value from a string with CHARACTER
>     SET 'binary'.` 오류로 실패합니다. `JSON_OBJECT()`나 `JSON_ARRAY()` 안에서는
> 허용되지만 base64로 인코딩되므로, `SELECT JSON_OBJECT('v', ai_prompt(...))`는
> `{"v": "base64:type15:UGFyaXMu"}`를 반환합니다. 해당 버전에서는 호출을
> `CONVERT(... USING utf8mb4)`로 감싸세요. 0.0.7 이상에서는 필요하지 않으며,
> 위의 예제가 그대로 실행됩니다.

> [!WARNING]
>
> 각 호출은 모델이 답하는 동안 해당 문을 차단하며, 각 호출에는 제공자가 청구하는
> 비용이 듭니다. 큰 테이블에서 행마다 한 번씩 호출하면 느리고 비쌉니다. 변수에
> 담은 키는 모델을 호출하는 문에는 나타나지 않지만, 키를 담는 `SET` 문은 키와
> 함께 쿼리 로그에 기록됩니다.

## 참고 항목

* [AI API 키 설정하기](https://villagesql.com/docs/en/guides/ai-api-setup.md) — 키를 둘 위치와 로그에 남기지 않는 방법
* [MySQL에서의 AI 프롬프트](https://villagesql.com/docs/en/guides/ai-prompts-in-mysql.md) — 테이블과 함께 써도 무너지지 않는 프롬프팅 패턴
* [벡터 임베딩 생성하기](https://villagesql.com/docs/en/guides/vector-embeddings.md) — 벡터 저장과 검색
* [확장 기능 설치](https://villagesql.com/docs/ko/extensions/install.md) — `INSTALL EXTENSION`의 동작 방식과 서버가 번들을 찾는 위치
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/extensions/catalog) — 전체 카탈로그
* [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) — 소스, 빌드 지침, 알려진 제한 사항


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.