MySQL용 vsql_ai 확장 기능

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


관리자	VillageSQL
소스 및 전체 문서	villagesql/vsql-ai
라이선스	GPL-2.0

설치

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

INSTALL EXTENSION vsql_ai;

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

SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_ai';

+----------------+
| EXTENSION_NAME |
+----------------+
| 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, 로컬 모델을 지원합니다.

예제

로컬 모델에 질문합니다:

SELECT ai_prompt('local', 'llama3.2', '', 'Reply with exactly one word: the capital of France.') AS answer;

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

모델은 자기 나름의 표현으로 답하므로, 실제 응답은 이것과 다를 수 있습니다. 텍스트를 벡터로 바꾸고 그 차원 수를 확인합니다:

SELECT JSON_LENGTH(ai_embedding('local', 'nomic-embed-text', '', 'Machine learning')) AS dimensions;

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

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

SET @api_key = '...';
SELECT ai_prompt('anthropic', 'claude-opus-5', @api_key, 'Hello!');

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 이상에서는 필요하지 않으며, 위의 예제가 그대로 실행됩니다.

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

참고 항목

AI API 키 설정하기 — 키를 둘 위치와 로그에 남기지 않는 방법
MySQL에서의 AI 프롬프트 — 테이블과 함께 써도 무너지지 않는 프롬프팅 패턴
벡터 임베딩 생성하기 — 벡터 저장과 검색
확장 기능 설치 — INSTALL EXTENSION의 동작 방식과 서버가 번들을 찾는 위치
사용 가능한 확장 기능 — 전체 카탈로그
villagesql/vsql-ai — 소스, 빌드 지침, 알려진 제한 사항

확장 기능 설치 및 실행

확장 기능 카탈로그

확장 기능 빌드

설치

추가되는 기능

예제

참고 항목

​설치

​추가되는 기능

​예제

​참고 항목

설치

추가되는 기능

예제

참고 항목