Ollama e Caddy: integrando Inteligência Artificial local ao SQL Server 2025

Amanda Nascimento

há 3 horas

10 min de leitura

Como configurar modelos de IA localmente, estabelecer uma comunicação segura com HTTPS e gerar embeddings diretamente pelo SQL Server 2025.

Obs: Fizemos isso em um ambiente de teste, em produção o Ollama nunca deverá ficar na mesma máquina do sql.

Com a chegada do SQL Server 2025, novas possibilidades surgiram para integrar Inteligência Artificial diretamente ao banco de dados.

Uma dessas possibilidades é utilizar modelos de IA executados localmente, sem depender obrigatoriamente de serviços de IA hospedados na nuvem.

Neste tutorial, vamos configurar duas ferramentas:

Ollama: plataforma que permite executar modelos de Inteligência Artificial localmente.
Caddy: servidor web que utilizaremos como proxy reverso para disponibilizar a API do Ollama por HTTPS.

Ao final, teremos um ambiente preparado para gerar embeddings e comparar a similaridade semântica entre textos utilizando comandos T-SQL.

O ambiente utilizado neste laboratório é composto por Windows, PowerShell, SQL Server 2025, SQL Server Management Studio (SSMS), Ollama e Caddy.

Este tutorial considera que o SQL Server, o Ollama e o Caddy estão instalados na mesma máquina. As configurações são destinadas a um ambiente local de estudos.

1. Entendendo a arquitetura: SQL Server + Caddy + Ollama

Antes de começar, é importante entender por que precisamos de um proxy reverso.

O SQL Server 2025 permite registrar modelos externos de embeddings por meio do comando CREATE EXTERNAL MODEL. Para realizar chamadas a esses modelos, exige um endpoint HTTPS com TLS.

Por padrão, o Ollama disponibiliza sua API localmente utilizando HTTP, na porta 11434.

Portanto, precisamos estabelecer uma comunicação entre as duas ferramentas.

A solução adotada foi utilizar o Caddy como intermediário pois o Ollama não entende informações com criptografia, por este motivo precisamos de um proxy no meio para o sql conseguir comunicar via https com o ollama sem criptografia.

Como funciona a comunicação:

O SQL Server envia uma requisição HTTPS ao Caddy.
O Caddy recebe a requisição e encaminha ao Ollama por HTTP.
O Ollama processa a solicitação utilizando o modelo de IA instalado.
A resposta retorna pelo Caddy ao SQL Server.

Dessa forma, o Caddy atua como proxy reverso, fornecendo uma camada HTTPS para a API local do Ollama.

Arquitetura do laboratório:

SQL Server 2025 → HTTPS → Caddy → HTTP → Ollama

Essa abordagem permite utilizar modelos locais respeitando o requisito de HTTPS do SQL Server.

É importante destacar que o trecho entre Caddy e Ollama utiliza HTTP. Por isso, ambos devem permanecer no mesmo ambiente local ou em uma rede adequadamente protegida.

Instalando o Ollama no Windows

O primeiro passo é instalar o Ollama, responsável por executar nossos modelos de Inteligência Artificial.

Download oficial:

https://ollama.com/download/windows

Após concluir a instalação, abra o PowerShell e execute:

ollama --version

Esse comando verifica a versão instalada.

Durante meu laboratório, utilizei o Ollama na versão 0.40.15.

2.1. Verificando a instalação

Caso o PowerShell não reconheça o comando ollama, podemos verificar diretamente se o executável está instalado.

Test-Path "$env:LOCALAPPDATA\Programs\Ollama\ollama.exe"

Se o resultado for True, significa que o arquivo foi encontrado no caminho informado.

Também podemos executar o programa diretamente:

& "$env:LOCALAPPDATA\Programs\Ollama\ollama.exe" --version

A saída esperada no ambiente utilizado foi:

ollama version is 0.40.15

Isso confirma que o executável está acessível.

2.2. Configurando a variável de ambiente PATH

Caso o comando ollama não funcione diretamente no terminal, podemos adicionar o diretório de instalação à variável de ambiente PATH do usuário.

No PowerShell, execute:

$OllamaPath = "$env:LOCALAPPDATA\Programs\Ollama"

$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")

if (($UserPath -split ';') -notcontains $OllamaPath) {

    [Environment]::SetEnvironmentVariable(
        "Path",
        "$UserPath;$OllamaPath",
        "User"
    )

}

$env:Path += ";$OllamaPath"

ollama --version

Esse procedimento permite executar os comandos do Ollama sem informar o caminho completo do executável.

2.3. Baixando modelos de Inteligência Artificial

Com o Ollama instalado, podemos baixar os modelos que utilizaremos.

Para instalar um modelo de linguagem pequeno:

ollama pull llama3.2:1b

Outros modelos disponíveis para experimentação:

Modelo de linguagem para conversação:

ollama pull llama3.1:8b

Modelo de embeddings:

ollama pull embeddinggemma

Modelo de embeddings utilizado neste laboratório:

ollama pull nomic-embed-text

Outro modelo de embeddings:

ollama pull mxbai-embed-large

Os modelos possuem finalidades e requisitos de memória diferentes.

Modelos de linguagem, como Llama, são utilizados para geração de respostas. Já modelos de embeddings transformam textos em representações vetoriais, permitindo realizar buscas e comparações por similaridade semântica.

Para este laboratório, utilizaremos o nomic-embed-text.

Para conferir os modelos instalados:

ollama list

Também é importante garantir que o serviço do Ollama esteja em execução antes de realizar os testes de integração.

3. Instalando o Caddy no Windows

O próximo passo é instalar o Caddy, que será responsável pela comunicação HTTPS entre o SQL Server e o Ollama.

Download oficial:

https://caddyserver.com/download

Após baixar o executável, crie a pasta:

C:\Caddy

Coloque o arquivo executável dentro dessa pasta.

No meu ambiente, o arquivo recebeu o nome:

C:\Caddy\caddy_windows_amd64.exe

3.1. Verificando a instalação

Abra o PowerShell e execute:

& "C:\Caddy\caddy_windows_amd64.exe" version

Se o comando retornar a versão do Caddy, o executável está funcionando.

4. Criando o arquivo de configuração do Caddy

O Caddy utiliza um arquivo de configuração chamado Caddyfile.

Esse arquivo define como as requisições serão recebidas e encaminhadas ao Ollama.

No nosso laboratório, o Caddy será configurado para:

Disponibilizar um endpoint HTTPS local.
Encaminhar requisições da API para o Ollama na porta 11434.
Utilizar certificados TLS gerenciados pelo próprio Caddy.
Registrar logs das requisições.

4.1. Criando a pasta de logs

No PowerShell:

New-Item -ItemType Directory -Path "C:\Caddy\logs" -Force

4.2. Criando o Caddyfile

Execute o comando abaixo para criar o arquivo automaticamente:

@'
{
    admin localhost:2019

    pki {
        ca local {
            intermediate_lifetime 52560h
        }
    }
}

localhost, 127.0.0.1 {
    tls {
        issuer internal {
            lifetime 43800h
        }
    }

    @ollama path /api/* /v1/*

    handle @ollama {
        reverse_proxy 127.0.0.1:11434 {
            flush_interval -1
        }
    }

    handle {
        respond "Caddy is running with HTTPS on localhost" 200
    }

    log {
        output file C:\Caddy\logs\ollama-local.log
        format console
    }
}
'@ | Set-Content -Path "C:\Caddy\Caddyfile" -Encoding ASCII

O arquivo acima mantém o objetivo da configuração utilizada no laboratório, priorizando a comunicação local.

Não incluí cabeçalhos CORS liberados para qualquer origem, pois eles não são necessários para as chamadas do SQL Server. Caso a API também seja consumida por aplicações no navegador, a configuração CORS deve ser avaliada separadamente.

Para confirmar a criação do arquivo:

Get-ChildItem "C:\Caddy"

4.3. Validando o arquivo de configuração

Antes de iniciar o servidor, precisamos verificar se o arquivo está correto.

Execute:

& "C:\Caddy\caddy_windows_amd64.exe" validate --config "C:\Caddy\Caddyfile" --adapter caddyfile

A saída esperada é:

Valid configuration

Isso significa que a configuração foi aceita pelo Caddy.

4.4. Iniciando o Caddy

Execute:

& "C:\Caddy\caddy_windows_amd64.exe" run --config "C:\Caddy\Caddyfile" --adapter caddyfile

O Caddy será iniciado e permanecerá em execução enquanto esse processo estiver ativo.

Mantenha esse terminal aberto durante os testes.

5. Testando a comunicação HTTPS

Agora precisamos verificar se o Caddy está respondendo corretamente.

Abra uma nova janela do PowerShell e execute:

Invoke-WebRequest -Uri "https://localhost" -UseBasicParsing

Se o certificado estiver sendo reconhecido e a configuração estiver correta, a resposta deverá indicar que o Caddy está em execução.

Mensagem configurada:

Caddy is running with HTTPS on localhost

5.1. Testando a comunicação Caddy → Ollama

Após confirmar que o HTTPS está funcionando, podemos verificar se o Caddy consegue encaminhar as requisições ao Ollama.

Execute:

Invoke-RestMethod `
    -Uri "https://localhost/api/tags" `
    -Method GET |
    Select-Object -ExpandProperty models |
    Select-Object name, size

Esse comando consulta a API do Ollama e retorna os modelos disponíveis.

Se os modelos instalados aparecerem, significa que o proxy está encaminhando as requisições corretamente.

6. Habilitando os recursos de IA no SQL Server 2025

Com o Ollama e o Caddy configurados, precisamos habilitar os recursos necessários no SQL Server.

Abra o SQL Server Management Studio (SSMS), conecte-se à instância SQL Server 2025 e abra uma nova consulta.

No laboratório, utilizei um banco chamado estudos.

Execute:

USE master;
GO

-- Habilitar recursos externos de IA
EXEC sp_configure
    'external AI runtimes enabled', 1;

RECONFIGURE WITH OVERRIDE;
GO

-- Habilitar chamadas REST externas
EXEC sp_configure
    'external rest endpoint enabled', 1;

RECONFIGURE WITH OVERRIDE;
GO

-- Selecionar banco de estudos
USE estudos;
GO

-- Habilitar funcionalidades em preview
ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;
GO

-- Conferir configurações
SELECT
    name,
    value,
    value_in_use
FROM sys.configurations
WHERE name IN (
    'external AI runtimes enabled',
    'external rest endpoint enabled'
);
GO

O recurso external rest endpoint enabled permite que o SQL Server realize chamadas a endpoints REST externos.

Já external AI runtimes enabled habilita a infraestrutura de execução de IA local, utilizada em outros cenários, como modelos ONNX. Mantive essa configuração por fazer parte da preparação do laboratório, embora não seja especificamente necessária para usar o Ollama via endpoint REST.

As funcionalidades em preview devem ser utilizadas em ambientes de estudo, observando a documentação e as limitações da versão instalada.

6.1. Verificando a configuração do banco

Execute:

USE estudos;
GO

SELECT
    name,
    value
FROM sys.database_scoped_configurations
WHERE name = 'PREVIEW_FEATURES';
GO

O resultado permite conferir se os recursos de preview estão habilitados no banco.

7. Registrando o modelo Ollama no SQL Server

Agora vamos registrar o modelo de embeddings nomic-embed-text no SQL Server.

Para isso, utilizaremos o comando CREATE EXTERNAL MODEL, disponível no SQL Server 2025.

Esse recurso permite cadastrar um modelo externo e utilizá-lo posteriormente em funções de IA do T-SQL.

O endereço configurado será:

https://localhost/api/embed

Esse endpoint HTTPS é disponibilizado pelo Caddy e encaminhado para a API do Ollama.

Execute no SSMS:

USE estudos;
GO

-- Registrar o modelo externo de embeddings

IF NOT EXISTS (
    SELECT 1
    FROM sys.external_models
    WHERE name = 'Ollama_Nomic'
)
BEGIN

    EXEC(N'
        CREATE EXTERNAL MODEL Ollama_Nomic
        WITH (
            LOCATION = ''https://localhost/api/embed'',
            API_FORMAT = ''Ollama'',
            MODEL_TYPE = EMBEDDINGS,
            MODEL = ''nomic-embed-text''
        );
    ');

END;
GO

-- Verificar o modelo registrado

SELECT
    name,
    model,
    location
FROM sys.external_models
WHERE name = 'Ollama_Nomic';
GO

O resultado esperado é o registro do modelo Ollama_Nomic.

Isso significa que o SQL Server possui um objeto apontando para o modelo disponibilizado pelo Ollama.

8. Configurando o certificado HTTPS

Como estamos utilizando HTTPS com certificados emitidos localmente pelo Caddy, precisamos garantir que o Windows confie na autoridade certificadora responsável.

O Caddy pode criar uma autoridade certificadora local e emitir certificados para o endereço localhost.

Para estabelecer uma conexão segura, o certificado precisa ser confiável no ambiente em que o cliente da conexão é executado.

8.1. Instalando a autoridade certificadora do Caddy

Abra o PowerShell como administrador e execute:

& "C:\Caddy\caddy_windows_amd64.exe" trust --config "C:\Caddy\Caddyfile"

Esse comando solicita a instalação da autoridade certificadora local do Caddy no repositório de certificados confiáveis do sistema.

Em ambientes nos quais a instalação automática não for possível, o certificado raiz poderá ser importado manualmente, após verificar sua origem.

Atenção: o comando Invoke-Item $Certificado apenas abre o arquivo indicado pela variável, caso ela contenha um caminho válido. Ele não garante, sozinho, que o certificado tenha sido instalado corretamente.

Também é necessário considerar que o SQL Server funciona como um serviço do Windows. Portanto, a cadeia de certificados deverá ser reconhecida pelo contexto em que o serviço executa as chamadas HTTPS.

9. Testando a conexão SQL Server → Caddy → Ollama

Agora chegou o momento de verificar se o SQL Server consegue acessar o Ollama por meio do Caddy.

No SSMS, execute:

USE estudos;
GO

-- Testar comunicação com o Ollama via HTTPS

DECLARE @Resposta NVARCHAR(MAX);

EXEC sys.sp_invoke_external_rest_endpoint
    @url = N'https://localhost/api/tags',
    @method = N'GET',
    @response = @Resposta OUTPUT;

-- Exibir resposta do Ollama

SELECT
    @Resposta AS Resposta_Ollama;
GO

Esse procedimento realiza uma requisição HTTPS diretamente pelo mecanismo do SQL Server.

A API /api/tags retorna informações sobre os modelos instalados no Ollama.

Se a execução for concluída com sucesso e a resposta contiver os modelos disponíveis, a comunicação estará funcionando.

Nesse momento, teremos validado a arquitetura:

SQL Server 2025 → Caddy → Ollama

Caso a chamada falhe, será necessário verificar as permissões do SQL Server, a disponibilidade do Caddy, a confiança no certificado e as regras de conectividade para endpoints locais.

Dica: Para facilitar a visualização e a leitura do JSON retornado pelo SQL Server, podemos copiar o conteúdo e utilizar o editor online Dillinger. Como ele é um editor Markdown, coloque o JSON entre três crases com a indicação json para melhorar a apresentação.. Também tem o validador de json JSONLint

10. Gerando nosso primeiro embedding

Com o modelo registrado, podemos gerar nosso primeiro embedding diretamente pelo SQL Server.

Mas o que é um embedding?

Um embedding é uma representação numérica gerada por um modelo de IA a partir de um conteúdo, como uma frase ou documento.

Esses números representam características semânticas do texto e permitem comparar informações de acordo com seus significados.

No SQL Server 2025, podemos gerar esses vetores utilizando a função AI_GENERATE_EMBEDDINGS.

Execute:

USE estudos;
GO

-- Gerar embedding usando o Ollama

SELECT
    AI_GENERATE_EMBEDDINGS(
        N'Estou aprendendo SQL Server 2025 com IA'
        USE MODEL Ollama_Nomic
    ) AS Vetor_Embedding;
GO

O SQL Server enviará o texto para o modelo nomic-embed-text, por meio do endpoint configurado anteriormente.

O modelo retornará um vetor numérico correspondente à frase informada.

O modelo nomic-embed-text utilizado neste exemplo gera vetores de 768 dimensões.

Esses vetores podem ser utilizados para realizar comparações semânticas, buscas por similaridade e, futuramente, aplicações com RAG (Retrieval-Augmented Generation).

11. Comparando a similaridade entre textos com IA

Agora vamos realizar um exemplo prático.

Imagine que temos três frases:

Quero aprender SQL Server.
Desejo estudar banco de dados.
Hoje está fazendo muito calor.

Mesmo que as duas primeiras frases utilizem palavras diferentes, seus significados estão relacionados.

A proposta é verificar se o modelo consegue identificar essa proximidade.

Para isso, utilizaremos duas funcionalidades do SQL Server 2025:

AI_GENERATE_EMBEDDINGS: transforma os textos em vetores.
VECTOR_DISTANCE: calcula a distância entre os vetores gerados.

Execute:

USE estudos;
GO

-- Criar frases para comparação

WITH Frases AS (

    SELECT
        1 AS ID,
        N'Quero aprender SQL Server' AS Texto

    UNION ALL

    SELECT
        2,
        N'Desejo estudar banco de dados'

    UNION ALL

    SELECT
        3,
        N'Hoje está fazendo muito calor'
),

Vetores AS (

    SELECT
        ID,
        Texto,

        -- Converter o retorno para VECTOR(768)

        CAST(
            AI_GENERATE_EMBEDDINGS(
                Texto USE MODEL Ollama_Nomic
            ) AS VECTOR(768)
        ) AS Embedding

    FROM Frases
)

-- Comparar similaridade entre textos

SELECT
    A.Texto AS Texto_Original,
    B.Texto AS Texto_Comparado,

    VECTOR_DISTANCE(
        'cosine',
        A.Embedding,
        B.Embedding
    ) AS Distancia

FROM Vetores A

CROSS JOIN Vetores B

WHERE A.ID = 1
  AND B.ID <> 1

ORDER BY Distancia ASC;
GO

Como interpretar o resultado?

A função VECTOR_DISTANCE calcula a distância entre as representações vetoriais.

Quanto menor a distância, maior tende a ser a similaridade semântica entre os textos, de acordo com o modelo utilizado.

Portanto, esperamos que a frase "Quero aprender SQL Server" apresente uma distância menor em relação a "Desejo estudar banco de dados" do que em relação a "Hoje está fazendo muito calor".

Essa comparação demonstra como podemos utilizar Inteligência Artificial para identificar relações entre informações que não possuem necessariamente as mesmas palavras.

É importante lembrar que os resultados dependem do modelo utilizado e que a distância vetorial não deve ser interpretada diretamente como um percentual de confiança.

12. O que aprendemos?

Ao longo deste tutorial, configuramos uma arquitetura local para integrar modelos de Inteligência Artificial ao SQL Server 2025.

Utilizamos o Ollama para executar modelos de IA localmente, o Caddy para fornecer um endpoint HTTPS e os recursos nativos do SQL Server para gerar e comparar embeddings.

Também exploramos alguns conceitos importantes:

Embeddings: representações numéricas que permitem trabalhar com o significado dos textos.

Vector Search: busca por similaridade entre vetores, que pode ser utilizada para localizar informações semanticamente relacionadas.

Banco vetorial: sistema que armazena e consulta representações vetoriais. O SQL Server 2025 oferece recursos para trabalhar com esse tipo de dado.

Índices vetoriais: estruturas que ajudam a acelerar buscas por similaridade em grandes volumes de vetores.

RAG (Retrieval-Augmented Generation): técnica que combina a recuperação de informações relevantes com modelos de linguagem para gerar respostas contextualizadas.

Referências

Ollama: https://ollama.com
Documentação do Ollama: https://docs.ollama.com
Caddy: https://caddyserver.com
SQL Server — CREATE EXTERNAL MODEL: https://learn.microsoft.com/sql/t-sql/statements/create-external-model-transact-sql
SQL Server — AI_GENERATE_EMBEDDINGS: https://learn.microsoft.com/sql/t-sql/functions/ai-generate-embeddings-transact-sql
SQL Server — VECTOR_DISTANCE: https://learn.microsoft.com/sql/t-sql/functions/vector-distance-transact-sql

AN

1. Entendendo a arquitetura: SQL Server + Caddy + Ollama

Instalando o Ollama no Windows

2.1. Verificando a instalação

2.2. Configurando a variável de ambiente PATH

2.3. Baixando modelos de Inteligência Artificial

3. Instalando o Caddy no Windows

3.1. Verificando a instalação

4. Criando o arquivo de configuração do Caddy

4.1. Criando a pasta de logs

4.2. Criando o Caddyfile

4.3. Validando o arquivo de configuração

4.4. Iniciando o Caddy

5. Testando a comunicação HTTPS

5.1. Testando a comunicação Caddy → Ollama

6. Habilitando os recursos de IA no SQL Server 2025

6.1. Verificando a configuração do banco

7. Registrando o modelo Ollama no SQL Server

8. Configurando o certificado HTTPS

8.1. Instalando a autoridade certificadora do Caddy

9. Testando a conexão SQL Server → Caddy → Ollama

10. Gerando nosso primeiro embedding

11. Comparando a similaridade entre textos com IA

Como interpretar o resultado?

12. O que aprendemos?