> ## 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.

# Conectando o MySQL a APIs de IA

> Como conectar o MySQL a APIs de IA usando a extensão vsql_ai do VillageSQL — instalando a extensão, configurando chaves de API e escolhendo um provedor e um modelo.

> [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 →

A extensão `vsql_ai` do VillageSQL permite chamar modelos de linguagem de IA diretamente de consultas SQL. Antes de executar seu primeiro `ai_prompt()`, você precisa da extensão instalada e de uma chave de API pronta. Este guia cobre a configuração, as opções de provedor e as considerações de segurança que importam antes de ir para produção.

## Instale a Extensão

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

Depois que uma chave de API estiver definida (veja abaixo), faça uma chamada de teste:

```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;
```

## Definindo Sua Chave de API

As funções `ai_prompt()` e `ai_embedding()` recebem a chave de API como parâmetro. O padrão recomendado é uma variável de sessão definida no momento da conexão — nunca incorpore um literal de chave em uma consulta que possa acabar em um arquivo de log. Para o provedor `'local'`, passe uma string vazia — nenhuma chave de API é necessária.

```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;
```

**O que evitar:**

```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');
```

Defina a variável de sessão na configuração de conexão da sua aplicação, não em SQL que você grava em um arquivo. A própria instrução `SET @key = '...'` é capturada literalmente, com a chave incluída, em `performance_schema.events_statements_history` — ativa por padrão no MySQL 8.4 — assim como em qualquer log geral ou de consultas lentas que você habilitar. Uma variável de sessão mantém a chave fora da *consulta* que a usa, mas não fora da instrução que a define. A única forma de evitar isso é nunca enviar a chave como texto SQL literal: vincule-a como parâmetro de uma instrução preparada, ou use um mecanismo de substituição no lado do cliente que nunca coloque o literal no texto SQL que o servidor analisa.

## Escolhendo um Provedor e um Modelo

### Anthropic

Melhor para: raciocínio complexo, documentos longos, geração de código e tarefas de seguimento de instruções.

```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);
```

**Modelos Claude:**

* `claude-fable-5` — o mais capaz, para raciocínio exigente e trabalho de longo horizonte
* `claude-opus-5` — padrão recomendado; codificação agêntica complexa e trabalho corporativo
* `claude-sonnet-5` — a melhor combinação de velocidade e inteligência
* `claude-haiku-4-5` — o mais rápido e com melhor custo-benefício

As gerações anteriores continuam suportadas: `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`.

A Anthropic não suporta `ai_embedding()`.

### Google Gemini

Melhor para: geração de embeddings e tarefas multimodais.

```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

Melhor para: geração de embeddings com a família `text-embedding-3`, amplamente adotada.

```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);
```

### Local (Ollama)

Melhor para: desenvolvimento local e dados privados que não podem sair da sua rede. Requer o [Ollama](https://ollama.com) em execução em `127.0.0.1:11434`. Nenhuma chave de API é necessária — passe uma string vazia.

```sql theme={null}
-- Prompting
SELECT ai_prompt('local', 'llama3.2', '', @prompt);

-- Embeddings
SELECT ai_embedding('local', 'nomic-embed-text', '', @text);
```

Use qualquer modelo que você tenha baixado no Ollama. Modelos de chat comuns: `llama3.2`, `mistral`, `gemma2`. Modelos de embedding comuns: `nomic-embed-text`, `mxbai-embed-large`.

### Comparação de provedores

| Provedor | Prompts | Embeddings | Melhor para |
| :- | :- | :- | :- |
| `'anthropic'` | Sim | Não | Raciocínio, instruções, código |
| `'google'` | Sim | Sim | Equilibrado; embeddings do Gemini |
| `'openai'` | Sim | Sim | Ecossistema OpenAI; text-embedding-3 |
| `'local'` | Sim | Sim | Ollama local; sem chave de API; dados privados |

## Considerações sobre Timeout e Limite de Taxa

As chamadas a APIs de IA levam de 5 a 30 segundos. O MySQL não limita a duração das consultas por padrão (`max_execution_time` é `0`, ilimitado), mas se a sua aplicação ou um pool de conexões o definir, uma chamada de IA de 30 segundos pode ser interrompida. Para sessões que executam consultas de IA, aumente ou confirme o limite explicitamente:

```sql theme={null}
SET SESSION max_execution_time = 60000;  -- 60 seconds
```

Para operações em lote sobre muitas linhas, isso importa — um UPDATE de 1000 linhas que chama `ai_prompt()` em cada linha pode levar mais de 30 minutos.

Todos os provedores impõem limites de taxa sobre quantas requisições você pode fazer por minuto. Atingir um limite de taxa faz `ai_prompt()` retornar NULL. Para operações em massa, processe em lotes de 50 a 100 linhas e adicione uma pausa entre os lotes no loop da sua aplicação. Consulte [Executando Modelos de IA a partir de Consultas MySQL](https://villagesql.com/docs/pt-BR/guides/ai-prompts-in-mysql.md) para padrões de lote.

## Perguntas Frequentes

#### Posso armazenar chaves de API em uma tabela do MySQL em vez de variáveis de sessão?

Pode, mas você está trocando um risco de segurança por outro. A abordagem com tabela exige um SELECT para ler a chave — essa consulta também aparece nos logs. Variáveis de sessão definidas programaticamente pelo framework da sua aplicação são a opção mais limpa.

#### O que acontece se a chamada à API falhar?

A função retorna NULL. Verifique se há NULL nos seus resultados durante os testes. Execute `SHOW WARNINGS` imediatamente após a chamada — a `vsql_ai` gera um `Warning 3200` com o motivo real da falha (chave inválida, provedor desconhecido, modelo não suportado etc.), o que é muito mais diagnóstico do que um NULL puro. Causas comuns: chave de API inválida, timeout de rede, limite de taxa atingido ou um nome de modelo não suportado.

#### Posso usar provedores diferentes na mesma consulta?

Sim — `ai_prompt()` é uma função comum. Você pode chamá-la com combinações diferentes de provedor/modelo no mesmo SELECT.

#### Os nomes dos modelos são estáveis?

Os provedores mudam os nomes dos modelos ao longo do tempo. Os nomes listados aqui correspondem aos modelos testados atualmente pela extensão. Consulte a documentação do seu provedor para os identificadores de modelo mais recentes disponíveis.

## Solução de Problemas

| Problema | Solução |
| :- | :- |
| `FUNCTION <database>.ai_prompt does not exist` | Execute `INSTALL EXTENSION vsql_ai` |
| `ai_prompt()` retorna NULL | Verifique se a chave de API é válida; verifique se `max_execution_time` está alto o suficiente; verifique o nome do modelo |
| A consulta atinge o timeout | Defina `SET SESSION max_execution_time = 60000` |
| A chave aparece no log de consultas lentas | Use uma variável de sessão definida pelo código da aplicação, não um literal de string SQL |

## Veja também

* [Executando Modelos de IA a partir de Consultas MySQL](https://villagesql.com/docs/pt-BR/guides/ai-prompts-in-mysql.md) — usando ai\_prompt() depois que a extensão está configurada
* [Gerando Embeddings Vetoriais no MySQL](https://villagesql.com/docs/pt-BR/guides/vector-embeddings.md) — usando ai\_embedding() para busca semântica


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