CRIAR MODELO EXTERNO (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Azure SQL Database SQLdatabase in Microsoft Fabric

Cria um objeto de modelo externo que contém o local, o método de autenticação e a finalidade de um ponto de extremidade de inferência do modelo de IA.

Sintaxe

Convenções de sintaxe de Transact-SQL

CREATE EXTERNAL MODEL external_model_object_name
[ AUTHORIZATION owner_name ]
WITH
  (   LOCATION = '<prefix>://<path>[:<port>]'
    , API_FORMAT = '<OpenAI, Azure OpenAI, etc>'
    , MODEL_TYPE = EMBEDDINGS
    , MODEL = 'text-embedding-model-name'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
    [ , LOCAL_RUNTIME_PATH = 'path to the ONNX Runtime files' ]
  );

Argumentos

external_model_object_name

Especifica o nome definido pelo usuário para o modelo externo. O nome deve ser exclusivo no banco de dados.

owner_name

Especifica o nome do usuário ou função que possui o modelo externo. Se você não especificar esse argumento, o usuário atual se torna o dono. Dependendo das permissões e funções, talvez seja necessário conceder permissão explícita aos usuários para usar modelos externos específicos.

LOCALIZAÇÃO

Fornece o protocolo de conectividade e o caminho para o ponto de extremidade de inferência do modelo de IA.

Formato_API

O formato de mensagem de API para o provedor de ponto de extremidade de inferência do modelo de IA.

Os valores aceitos são:

• Azure OpenAI
• OpenAI
• Ollama
• ONNX Runtime

TIPO_DE_MODELO

O tipo de modelo acessado a partir da localização do endpoint de inferência do modelo de IA.

Os valores aceitos são:

• EMBEDDINGS

MODELO

O modelo específico hospedado pelo provedor de IA. Por exemplo, text-embedding-ada-002, text-embedding-3-large ou o3-mini.

CREDENCIAL

Especifica o DATABASE SCOPED CREDENTIAL objeto usado com o endpoint de inferência do modelo de IA. Para mais informações sobre tipos de credenciais aceitos e regras de nomeação, veja sp_invoke_external_rest_endpoint ou a seção de Observações deste artigo.

PARÂMETROS

Uma string JSON válida que contenha parâmetros de runtime para adicionar à mensagem de solicitação de endpoint de inferência do modelo de IA. Por exemplo:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH especifica o diretório na instância local do SQL Server onde os executáveis de tempo de execução ONNX estão localizados.

Permissões

Criação e alteração de modelo externo

ALTER ANY EXTERNAL MODEL Requer ou CREATE EXTERNAL MODEL permissão de banco de dados.

Por exemplo:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Ou:

GRANT ALTER ANY EXTERNAL MODEL TO [<PRINCIPAL>];

Concessões de modelo externo

Para usar um modelo externo em uma função de IA, uma entidade de segurança deve receber a capacidade dela EXECUTE .

Por exemplo:

GRANT EXECUTE ON EXTERNAL MODEL::MODEL_NAME TO [<PRINCIPAL>];
GO

Número de tentativas

Se a chamada de inserções encontrar códigos de status HTTP indicando problemas temporários, você poderá configurar a solicitação para tentar novamente automaticamente. Para especificar o número de repetições, adicione o JSON a PARAMETERSEXTERNAL MODELseguir ao . O <number_of_retries> deve ser um número inteiro entre zero (0) e dez (10), inclusive, e não pode ser NULL ou negativo.

{ "sql_rest_options": { "retry_count": <number_of_retries> } }

Por exemplo, para definir o retry_count para 3, use a seguinte string JSON:

{ "sql_rest_options": { "retry_count": 3 } }

Contagem de repetição com outros parâmetros

Você pode combinar a contagem de tentativas com outros parâmetros, desde que a string JSON seja válida.

{ "dimensions": 725, "sql_rest_options": { "retry_count": 5 } }

Observações

HTTPS e TLS

Para o LOCATION parâmetro, apenas os endpoints de inferência do modelo de IA configurados para usar HTTPS com o protocolo de criptografia TLS são suportados.

Formatos de API e tipos de modelo aceitos

As seções a seguir descrevem formatos de API aceitos para cada MODEL_TYPE.

API_FORMAT para EMBEDDINGS

Esta tabela descreve os formatos da API e as estruturas de endpoints URL para o EMBEDDINGS tipo de modelo. Para exibir estruturas de conteúdo específicas, use o link na coluna Formato da API.

Formato de API	Formato do caminho de localização
OpenAI do Azure	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	https://{server_name}/v1/embeddings
Ollama	https://localhost:{port}/api/inbed

Criar pontos de extremidade de inserção

Para obter mais informações sobre como criar pontos de extremidade de inserção, use estes links para o provedor de ponto de extremidade de inferência do modelo de IA apropriado:

• Azure OpenAI nos modelos do Azure AI Foundry
• OpenAI
• Ollama

Regras de nome de credencial para modelo externo

O criado DATABASE SCOPED CREDENTIAL usado por um modelo externo deve seguir estas regras:

• Deve ser um URL válido

• O domínio URL deve ser um daqueles domínios incluídos na lista de permitidos.

• A URL não deve conter uma cadeia de caracteres de consulta

• Protocolo + FQDN (Nome de Domínio Totalmente Qualificado) da URL chamada deve corresponder ao Protocolo + FQDN do nome da credencial

• Cada parte do caminho URL chamado deve corresponder completamente à respectiva parte do caminho da URL no nome da credencial.

• A credencial deve apontar para um caminho mais genérico do que a URL do pedido. Por exemplo, uma credencial criada para path https://northwind.azurewebsite.net/customers não pode ser usada para a URL https://northwind.azurewebsite.net.

Regras de ordenação e nome de credencial

A Seção 6.2.2.1 do RFC 3986 afirma que "Quando um URI usa componentes da sintaxe genérica, as regras de equivalência da sintaxe dos componentes sempre se aplicam; ou seja, que o esquema e o host não são distintos a maiúsculas e minúsculas." A Seção 2.7.3 do RFC 7230 menciona que "todas as outras são comparadas de forma sensível a maiúsculas e minúsculas."

Como uma regra de colação é definida no nível do banco de dados, a seguinte lógica se aplica para manter a regra de colação do banco de dados e as regras de RFC consistentes. (A regra descrita pode ser potencialmente mais restritiva do que as regras do RFC, por exemplo, se o banco de dados estiver configurado para usar uma colação sensível a maiúsculas e minúsculas.)

1. Verifique se a URL e a credencial correspondem usando o RFC, o que significa:

   • Verifique o esquema e o host usando uma ordenação que não diferencia maiúsculas de minúsculas (Latin1_General_100_CI_AS_KS_WS_SC)
   • Verifique se todos os outros segmentos do URL são comparados em um agrupamento que diferencia maiúsculas de minúsculas (Latin1_General_100_BIN2)

2. Verifique se a URL e a credencial correspondem usando as regras de agrupamento do banco de dados (e sem fazer nenhuma codificação de URL).

Identidade gerenciada

Para usar a identidade gerenciada do host Arc/VM como credencial em nível de banco de dados no SQL Server 2025 (17.x), você deve habilitar a opção usando sp_configure com um usuário que receba a permissão ALTER SETTINGS em nível de servidor.

EXECUTE sp_configure 'allow server scoped db credentials', 1;
RECONFIGURE WITH OVERRIDE;

SCHEMABINDING

Views criadas com SCHEMABINDING isso fazem referência a um modelo externo (como uma SELECT instrução usando AI_GENERATE_EMBEDDINGS) não podem ser descartadas, e o Mecanismo de Banco de Dados gera um erro. Para remover dependências que referenciam um modelo externo, você deve primeiro modificar ou eliminar a definição de view.

Visualização do catálogo

Você pode visualizar metadados externos de modelos consultando a visualização de catálogo sys.external_models . Você precisa ter acesso a um modelo para visualizar seus metadados.

SELECT *
FROM sys.external_models;

Exemplos com pontos de extremidade remotos

Criar um MODELO EXTERNO com o Azure OpenAI usando a Identidade Gerenciada

Este exemplo cria um modelo externo do EMBEDDINGS tipo usando Azure OpenAI e utiliza Identidade Gerenciada para autenticação.

No SQL Server 2025 (17.x) e versões posteriores, você deve conectar seu SQL Server ao Azure Arc e ativar a identidade gerenciada principal.

Importante

Se você usar Identidade Gerenciada com Azure OpenAI e SQL Server 2025 (17.x), a função de Contribuidor OpenAI de Serviços Cognitivos deve ser concedida à identidade gerenciada atribuída ao sistema do SQL Server habilitada pelo Azure Arc. Para mais informações, veja Controle de acesso baseado em funções para Azure OpenAI em Azure AI Foundry Models.

Crie credenciais de acesso ao Azure OpenAI usando uma identidade gerenciada:

CREATE DATABASE SCOPED CREDENTIAL [https://my-azure-openai-endpoint.cognitiveservices.azure.com/]
    WITH IDENTITY = 'Managed Identity', secret = '{"resourceid":"https://cognitiveservices.azure.com"}';
GO

Crie o modelo externo:

CREATE EXTERNAL MODEL MyAzureOpenAIModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.cognitiveservices.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2024-02-01',
      API_FORMAT = 'Azure OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-ada-002',
      CREDENTIAL = [https://my-azure-openai-endpoint.cognitiveservices.azure.com/]
);

Crie um modelo externo com Azure OpenAI usando chaves e parâmetros de API

Este exemplo cria um modelo externo do EMBEDDINGS tipo usando Azure OpenAI e utiliza APIs Keys para autenticação. O exemplo também usa PARAMETERS para definir o parâmetro de dimensões no ponto de extremidade como 725.

Crie credenciais de acesso ao Azure OpenAI usando uma chave:

CREATE DATABASE SCOPED CREDENTIAL [https://my-azure-openai-endpoint.cognitiveservices.azure.com/]
    WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"api-key":"YOUR_AZURE_OPENAI_KEY"}';
GO

Crie o modelo externo:

CREATE EXTERNAL MODEL MyAzureOpenAIModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.cognitiveservices.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-02-01',
      API_FORMAT = 'Azure OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-3-small',
      CREDENTIAL = [https://my-azure-openai-endpoint.cognitiveservices.azure.com/],
      PARAMETERS = '{"dimensions":725}'
);

Criar um MODELO EXTERNO com o Ollama e um proprietário explícito

Este exemplo cria um modelo externo do EMBEDDINGS tipo usando o Ollama hospedado localmente para fins de desenvolvimento.

CREATE EXTERNAL MODEL MyOllamaModel
AUTHORIZATION AI_User
WITH (
      LOCATION = 'https://localhost:11435/api/embed',
      API_FORMAT = 'Ollama',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'all-minilm'
);

Criar um MODELO EXTERNO com OpenAI

Este exemplo cria um modelo externo do EMBEDDINGS tipo usando as credenciais baseadas em cabeçalhos do OpenAI API_FORMAT e HTTP para autenticação.

-- Create access credentials
CREATE DATABASE SCOPED CREDENTIAL [https://openai.com]
WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"Bearer":"YOUR_OPENAI_KEY"}';
GO

-- Create the external model
CREATE EXTERNAL MODEL MyAzureOpenAIModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://api.openai.com/v1/embeddings',
      API_FORMAT = 'OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-ada-002',
      CREDENTIAL = [https://openai.com]
);

Exemplo com o ONNX Runtime rodando localmente

O ONNX Runtime é um mecanismo de inferência de software livre que permite executar modelos de machine learning localmente, tornando-o ideal para integrar recursos de IA em ambientes do SQL Server.

Este exemplo guia você na configuração do SQL Server 2025 (17.x) com o ONNX Runtime para possibilitar a geração local de embedding de texto alimentada por IA. Ele só se aplica ao Windows.

Importante

Esse recurso requer que os Serviços de Machine Learning do SQL Server sejam instalados.

Etapa 1: Habilitar recursos de visualização do desenvolvedor no SQL Server 2025

Execute o seguinte comando Transact-SQL (T-SQL) para habilitar recursos de pré-visualização do SQL Server 2025 (17.x) no banco de dados que você deseja usar neste exemplo:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Etapa 2: Habilitar o runtime de IA local no SQL Server 2025

Ative runtimes de IA externa executando a seguinte consulta T-SQL:

EXECUTE sp_configure 'external AI runtimes enabled', 1;
RECONFIGURE WITH OVERRIDE;

Passo 3: Configurar a biblioteca de tempo de execução ONNX

Crie um diretório na instância do SQL Server para armazenar os arquivos da biblioteca de tempo de execução ONNX. Neste exemplo, C:\onnx_runtime é usado.

Você pode usar os seguintes comandos para criar o diretório:

cd C:\
mkdir onnx_runtime

Em seguida, baixe uma versão do ONNX Runtime (1.19 ou superior) que seja adequada para o seu sistema operacional. Depois de descompactar o download, copie o onnxruntime.dll (localizado no diretório lib) para o C:\onnx_runtime diretório que foi criado.

Etapa 4: Configurar a biblioteca de tokens

Baixe e crie a tokenizers-cpp biblioteca no GitHub. Depois que a dll for criada, coloque o tokenizador no C:\onnx_runtime diretório.

Observação

Verifique se a dll criada é nomeada tokenizers_cpp.dll

Etapa 5: Baixar o modelo ONNX

Comece criando o model diretório em C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

Este exemplo usa o all-MiniLM-L6-v2-onnx modelo, que pode ser baixado do Hugging Face.

Clone o repositório no C:\onnx_runtime\model diretório com o seguinte comando git :

Se não estiver instalado, você poderá baixar o Git no link de download a seguir ou por meio do winget (winget install Microsoft.Git)

cd C:\onnx_runtime\model
git clone https://huggingface.co/nsense/all-MiniLM-L6-v2-onnx

Etapa 6: Definir permissões de diretório

Use o seguinte script PowerShell para fornecer ao usuário MSSQLLaunchpad acesso ao diretório de tempo de execução ONNX:

$AIExtPath = "C:\onnx_runtime";
$Acl = Get-Acl -Path $AIExtPath
$AccessRule = New-Object System.Security.AccessControl.FileSystemAccessRule("MSSQLLaunchpad", "FullControl", "ContainerInherit,ObjectInherit", "None","Allow")
$Acl.AddAccessRule($AccessRule)
Set-Acl -Path $AIExtPath -AclObject $Acl

Etapa 7: Criar o modelo externo

Execute a seguinte consulta para registrar seu modelo ONNX como um objeto de modelo externo:

O valor 'PARAMETERS' usado aqui é um marcador necessário para o SQL Server 2025 (17.x).

CREATE EXTERNAL MODEL myLocalOnnxModel
WITH (
    LOCATION = 'C:\onnx_runtime\model\all-MiniLM-L6-v2-onnx',
    API_FORMAT = 'ONNX Runtime',
    MODEL_TYPE = EMBEDDINGS,
    MODEL = 'allMiniLM',
    PARAMETERS = '{"valid":"JSON"}',
    LOCAL_RUNTIME_PATH = 'C:\onnx_runtime\'
);

• LOCATION deve apontar para o diretório que contém model.onnx e tokenizer.json arquivos.
• LOCAL_RUNTIME_PATH deve apontar para o diretório que contém onnxruntime.dll e tokenizer_cpp.dll arquivos.

Etapa 8: Gerar inserções

Use a ai_generate_embeddings função para testar o modelo executando a seguinte consulta:

SELECT AI_GENERATE_EMBEDDINGS(N'Test Text' USE MODEL myLocalOnnxModel);

Esse comando inicia as AIRuntimeHostDLLs necessárias e processa o texto de entrada.

O resultado da consulta anterior é um array de embeddings:

[0.320098,0.568766,0.154386,0.205526,-0.027379,-0.149689,-0.022946,-0.385856,-0.039183...]

Habilitar o registro do sistema XEvent

Execute a seguinte consulta para habilitar o registro do sistema para resolução de problemas.

CREATE EVENT SESSION newevt
ON SERVER
ADD EVENT ai_generate_embeddings_airuntime_trace
(
    ACTION (sqlserver.sql_text, sqlserver.session_id)
)
ADD TARGET package0.ring_buffer
WITH (MAX_MEMORY = 4096 KB, EVENT_RETENTION_MODE = ALLOW_SINGLE_EVENT_LOSS, MAX_DISPATCH_LATENCY = 30 SECONDS, TRACK_CAUSALITY = ON, STARTUP_STATE = OFF);
GO

ALTER EVENT SESSION newevt ON SERVER STATE = START;
GO

Em seguida, use esta consulta e veja os registros do sistema capturados:

SELECT event_data.value('(@name)[1]', 'varchar(100)') AS event_name,
       event_data.value('(@timestamp)[1]', 'datetime2') AS [timestamp],
       event_data.value('(data[@name = "model_name"]/value)[1]', 'nvarchar(200)') AS model_name,
       event_data.value('(data[@name = "phase_name"]/value)[1]', 'nvarchar(100)') AS phase,
       event_data.value('(data[@name = "message"]/value)[1]', 'nvarchar(max)') AS message,
       event_data.value('(data[@name = "request_id"]/value)[1]', 'nvarchar(max)') AS session_id,
       event_data.value('(data[@name = "error_code"]/value)[1]', 'bigint') AS error_code
FROM (SELECT CAST (target_data AS XML) AS target_data
      FROM sys.dm_xe_sessions AS s
           INNER JOIN sys.dm_xe_session_targets AS t
               ON s.address = t.event_session_address
      WHERE s.name = 'newevt'
            AND t.target_name = 'ring_buffer') AS data
CROSS APPLY target_data.nodes('//RingBufferTarget/event') AS XEvent(event_data);

Limpeza

Para remover o objeto modelo externo, execute a seguinte instrução T-SQL:

DROP EXTERNAL MODEL myLocalOnnxModel;

Para remover as permissões de diretório, execute os seguintes comandos do PowerShell:

$Acl.RemoveAccessRule($AccessRule)
Set-Acl -Path $AIExtPath -AclObject $Acl

Por fim, exclua o C:/onnx_runtime diretório.

Conteúdo relacionado

• ALTERAR MODELO EXTERNO (Transact-SQL)
• DESCARTE MODELO EXTERNO (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sys.external_models
• Criar e implantar um Azure OpenAI no recurso Azure AI Foundry Models
• Opções de configuração do servidor
• Controle de acesso baseado em função para o Azure OpenAI nos Modelos de AI Foundry do Azure