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

# Extensão vsql_ai para MySQL

> A extensão vsql_ai chama os modelos Claude, Gemini, OpenAI e Ollama local a partir do SQL, retornando respostas a prompts e vetores de embedding dentro de uma consulta.

A maior parte do trabalho de IA em bancos de dados segue o mesmo formato: ler
linhas, enviá-las a um modelo, esperar, gravar as respostas de volta. O
`vsql_ai` elimina o meio chamando o modelo a partir do SQL. Duas funções dão
conta disso, uma para um prompt e outra para um embedding. A função de prompt
funciona com Anthropic Claude, Google Gemini, OpenAI ou um modelo executado
localmente por meio do Ollama. A função de embedding funciona com todos esses,
exceto a Anthropic.

| | |
| - | - |
| **Mantenedor** | VillageSQL |
| **Código-fonte e documentação completa** | [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) |
| **Licença** | GPL-2.0 |

## Instalar

O `vsql_ai.veb` já está no diretório `lib/veb/` do servidor se você instalou o
VillageSQL com o script de instalação, a imagem Docker ou um tarball de
release. Instale-o no servidor com uma única instrução:

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

Confirme que ele está lá:

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

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

Para compilá-lo você mesmo, siga as instruções de compilação no
[repositório](https://github.com/villagesql/vsql-ai).

## O que ela adiciona

| Função | Retorna | O que faz |
| - | - | - |
| `ai_prompt(provider, model, api_key, prompt)` | texto | Envia um prompt e retorna a resposta do modelo |
| `ai_embedding(provider, model, api_key, text)` | texto | Retorna o vetor de embedding como um array JSON |

`provider` é `anthropic`, `google`, `openai` ou `local`. Um modelo local é
executado por meio do Ollama e recebe uma chave de API vazia. O `ai_embedding`
oferece suporte a modelos do Google, da OpenAI e locais.

## Exemplo

Faça uma pergunta a um modelo local:

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

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

Um modelo responde com as suas próprias palavras, então a sua resposta será diferente dessa.

Transforme texto em um vetor e verifique a sua largura:

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

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

Um provedor hospedado recebe a mesma chamada com uma chave:

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

> [!NOTE]
>
> No VillageSQL 0.0.6 e anteriores, o resultado carrega o conjunto de
> caracteres binary, e duas coisas decorrem disso. Uma função JSON ou uma
> coluna `JSON` o rejeita, então o exemplo de embedding acima falha ali com
> `ERROR 3144 (22032): Cannot create a JSON value from a string with CHARACTER
>     SET 'binary'.` Dentro de `JSON_OBJECT()` ou `JSON_ARRAY()` ele é aceito, mas
> codificado em base64, então `SELECT JSON_OBJECT('v', ai_prompt(...))` retorna
> `{"v": "base64:type15:UGFyaXMu"}`. Envolva a chamada em
> `CONVERT(... USING utf8mb4)` nessas versões. Isso não é necessário no 0.0.7
> e posteriores, onde os exemplos acima rodam como estão escritos.

> [!WARNING]
>
> Cada chamada bloqueia a sua instrução enquanto o modelo responde, e cada
> chamada custa o que o provedor cobra. Uma chamada por linha em uma tabela
> grande é lenta e cara. Uma chave guardada em uma variável fica fora da
> instrução que chama o modelo, mas a instrução `SET` que a guarda é gravada
> no log de consultas com a chave.

## Veja também

* [Configurando uma chave de API de IA](https://villagesql.com/docs/en/guides/ai-api-setup.md) — onde colocar a chave e como mantê-la fora dos logs
* [Prompts de IA no MySQL](https://villagesql.com/docs/en/guides/ai-prompts-in-mysql.md) — padrões de prompting que sobrevivem ao contato com uma tabela
* [Gerando embeddings vetoriais](https://villagesql.com/docs/en/guides/vector-embeddings.md) — armazenar vetores e pesquisá-los
* [Instalar extensões](https://villagesql.com/docs/pt-BR/extensions/install.md) — como o `INSTALL EXTENSION` funciona e onde o servidor procura um bundle
* [Extensões disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) — o catálogo completo
* [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) — código-fonte, instruções de compilação e as limitações conhecidas


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