> ## 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을 AI API에 연결하기 > VillageSQL의 vsql_ai 확장을 사용하여 MySQL을 AI API에 연결하는 방법 — 확장 설치, API 키 구성, 공급자와 모델 선택. > [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md) > > All examples on this page work on VillageSQL. Install Now → VillageSQL의 `vsql_ai` 확장을 사용하면 SQL 쿼리에서 AI 언어 모델을 직접 호출할 수 있습니다. 첫 번째 `ai_prompt()`를 실행하기 전에 확장을 설치하고 API 키를 준비해야 합니다. 이 가이드는 설정, 공급자 옵션, 그리고 프로덕션에 적용하기 전에 중요한 보안 고려 사항을 다룹니다. ## 확장 설치 ```sql theme={null} INSTALL EXTENSION vsql_ai; ``` API 키를 설정한 후(아래 참조) 테스트 호출을 실행합니다: ```sql theme={null} SET @anthropic_key = 'sk-ant-your-key-here'; SELECT ai_prompt('anthropic', 'claude-haiku-4-5', @anthropic_key, 'Say hello') AS test; ``` ## API 키 설정 `ai_prompt()`와 `ai_embedding()` 함수는 API 키를 매개변수로 받습니다. 권장 패턴은 연결 시점에 설정하는 세션 변수입니다 — 로그 파일에 남을 수 있는 쿼리에 키 리터럴을 절대 포함하지 마세요. `'local'` 공급자의 경우 빈 문자열을 전달하세요 — API 키가 필요하지 않습니다. ```sql theme={null} -- Set once per connection, use everywhere SET @anthropic_key = 'sk-ant-your-key-here'; SET @openai_key = 'sk-your-openai-key'; SET @google_key = 'your-google-ai-key'; -- Then use the variable SELECT ai_prompt('anthropic', 'claude-haiku-4-5', @anthropic_key, 'Hello') AS response; ``` **피해야 할 것:** ```sql theme={null} -- Don't do this — key is visible in slow query logs and PROCESSLIST SELECT ai_prompt('anthropic', 'claude-haiku-4-5', 'sk-ant-12345...', 'Hello'); ``` 세션 변수는 파일에 작성하는 SQL이 아니라 애플리케이션의 연결 설정 코드에서 설정하세요. `SET @key = '...'` 문 자체는 키를 포함하여 그대로 `performance_schema.events_statements_history`(MySQL 8.4에서 기본 활성화)와 활성화한 모든 일반 로그 또는 슬로우 쿼리 로그에 기록됩니다. 세션 변수는 키를 사용하는 *쿼리*에서는 키를 숨기지만, 키를 설정하는 문에서는 숨기지 못합니다. 이를 피하는 유일한 방법은 키를 리터럴 SQL 텍스트로 전혀 보내지 않는 것입니다. 프리페어드 스테이트먼트 매개변수로 바인딩하거나, 서버가 파싱하는 SQL 텍스트에 리터럴을 절대 넣지 않는 클라이언트 측 치환 메커니즘을 사용하세요. ## 공급자와 모델 선택 ### Anthropic 적합한 용도: 복잡한 추론, 긴 문서, 코드 생성, 지시 사항 수행 작업. ```sql theme={null} -- Fast and cost-effective SELECT ai_prompt('anthropic', 'claude-haiku-4-5', @anthropic_key, @prompt); -- Balanced — speed and intelligence SELECT ai_prompt('anthropic', 'claude-sonnet-5', @anthropic_key, @prompt); -- Recommended default — complex agentic and enterprise work SELECT ai_prompt('anthropic', 'claude-opus-5', @anthropic_key, @prompt); ``` **Claude 모델:** * `claude-fable-5` — 가장 뛰어난 성능, 까다로운 추론과 장기 작업용 * `claude-opus-5` — 권장 기본값; 복잡한 에이전트 코딩과 엔터프라이즈 작업 * `claude-sonnet-5` — 속도와 지능의 최적 조합 * `claude-haiku-4-5` — 가장 빠르고 비용 효율적 이전 세대도 계속 지원됩니다: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`. Anthropic은 `ai_embedding()`을 지원하지 않습니다. ### Google Gemini 적합한 용도: 임베딩 생성과 멀티모달 작업. ```sql theme={null} -- Prompting SELECT ai_prompt('google', 'gemini-2.5-flash', @google_key, @prompt); -- Embeddings (3072 dimensions) SELECT ai_embedding('google', 'gemini-embedding-001', @google_key, @text); ``` ### OpenAI 적합한 용도: 널리 사용되는 `text-embedding-3` 제품군을 이용한 임베딩 생성. ```sql theme={null} -- Prompting SELECT ai_prompt('openai', 'gpt-4o-mini', @openai_key, @prompt); -- Embeddings (1536 dimensions) SELECT ai_embedding('openai', 'text-embedding-3-small', @openai_key, @text); -- Embeddings (3072 dimensions — higher accuracy) SELECT ai_embedding('openai', 'text-embedding-3-large', @openai_key, @text); ``` ### 로컬(Ollama) 적합한 용도: 로컬 개발과 네트워크 밖으로 나갈 수 없는 비공개 데이터. `127.0.0.1:11434`에서 실행 중인 [Ollama](https://ollama.com)가 필요합니다. API 키는 필요하지 않습니다 — 빈 문자열을 전달하세요. ```sql theme={null} -- Prompting SELECT ai_prompt('local', 'llama3.2', '', @prompt); -- Embeddings SELECT ai_embedding('local', 'nomic-embed-text', '', @text); ``` Ollama에서 가져온 모든 모델을 사용할 수 있습니다. 일반적인 채팅 모델: `llama3.2`, `mistral`, `gemma2`. 일반적인 임베딩 모델: `nomic-embed-text`, `mxbai-embed-large`. ### 공급자 비교 | 공급자 | 프롬프트 | 임베딩 | 적합한 용도 | | :- | :- | :- | :- | | `'anthropic'` | 예 | 아니요 | 추론, 지시 사항, 코드 | | `'google'` | 예 | 예 | 균형 잡힌 용도; Gemini 임베딩 | | `'openai'` | 예 | 예 | OpenAI 생태계; text-embedding-3 | | `'local'` | 예 | 예 | 로컬 Ollama; API 키 불필요; 비공개 데이터 | ## 타임아웃과 속도 제한 고려 사항 AI API 호출은 5–30초가 걸립니다. MySQL은 기본적으로 쿼리 실행 시간을 제한하지 않지만(`max_execution_time`은 `0`, 무제한), 애플리케이션이나 연결 풀이 이 값을 설정하면 30초짜리 AI 호출이 중단될 수 있습니다. AI 쿼리를 실행하는 세션에서는 제한을 명시적으로 높이거나 확인하세요: ```sql theme={null} SET SESSION max_execution_time = 60000; -- 60 seconds ``` 많은 행에 대한 일괄 작업에서는 이것이 중요합니다 — 각 행마다 `ai_prompt()`를 호출하는 1000행 UPDATE는 30분 이상 걸릴 수 있습니다. 모든 공급자는 분당 요청 수에 속도 제한을 적용합니다. 속도 제한에 걸리면 `ai_prompt()`는 NULL을 반환합니다. 대량 작업의 경우 50–100행 단위로 배치 처리하고, 애플리케이션 루프에서 배치 사이에 일시 정지를 추가하세요. 배치 패턴은 [MySQL 쿼리에서 AI 모델 실행하기](https://villagesql.com/docs/ko/guides/ai-prompts-in-mysql.md)를 참조하세요. ## 자주 묻는 질문 #### 세션 변수 대신 MySQL 테이블에 API 키를 저장할 수 있나요? 가능하지만, 하나의 보안 위험을 다른 위험과 맞바꾸는 것입니다. 테이블 방식은 키를 읽기 위해 SELECT가 필요하며, 그 쿼리도 로그에 남습니다. 애플리케이션 프레임워크가 프로그래밍 방식으로 설정하는 세션 변수가 가장 깔끔한 선택입니다. #### API 호출이 실패하면 어떻게 되나요? 함수는 NULL을 반환합니다. 테스트할 때 결과에서 NULL을 확인하세요. 호출 직후 `SHOW WARNINGS`를 실행하세요 — `vsql_ai`는 실제 실패 원인(잘못된 키, 알 수 없는 공급자, 지원되지 않는 모델 등)을 담은 `Warning 3200`을 발생시키며, 이는 단순한 NULL보다 훨씬 진단에 유용합니다. 일반적인 원인: 잘못된 API 키, 네트워크 타임아웃, 속도 제한 도달, 지원되지 않는 모델 이름. #### 같은 쿼리에서 다른 공급자를 사용할 수 있나요? 예 — `ai_prompt()`는 일반 함수입니다. 같은 SELECT에서 다른 공급자/모델 조합으로 호출할 수 있습니다. #### 모델 이름은 안정적인가요? 공급자는 시간이 지나면서 모델 이름을 변경합니다. 여기에 나열된 이름은 확장에서 현재 테스트된 모델과 일치합니다. 최신 모델 식별자는 공급자의 문서를 확인하세요. ## 문제 해결 | 문제 | 해결 방법 | | :- | :- | | `FUNCTION .ai_prompt does not exist` | `INSTALL EXTENSION vsql_ai` 실행 | | `ai_prompt()`가 NULL을 반환함 | API 키가 유효한지 확인; `max_execution_time`이 충분히 높게 설정되었는지 확인; 모델 이름 확인 | | 쿼리가 타임아웃됨 | `SET SESSION max_execution_time = 60000` 설정 | | 슬로우 쿼리 로그에 키가 나타남 | SQL 문자열 리터럴 대신 애플리케이션 코드가 설정하는 세션 변수 사용 | ## 참고 * [MySQL 쿼리에서 AI 모델 실행하기](https://villagesql.com/docs/ko/guides/ai-prompts-in-mysql.md) — 확장을 구성한 후 ai\_prompt() 사용하기 * [MySQL에서 벡터 임베딩 생성하기](https://villagesql.com/docs/ko/guides/vector-embeddings.md) — 의미 검색을 위한 ai\_embedding() 사용하기 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.