CREATE EXTERNAL MODEL (Transact-SQL)

Applies to: SQL Server 2025 (17.x) Banco de Dados SQL do Azure< Banco de dados Instância Gerenciada de SQL do AzureSQL em 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.

Observação

CREATE EXTERNAL MODEL está disponível em Instância Gerenciada de SQL do Azure com a política Always-up-to-dateupdate policy.

Sintaxe

Transact-SQL convenções de sintaxe

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 de SQL Server local em que os executáveis do OnNX Runtime 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
Azure OpenAI	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 em modelos Fábrica de IA do Azure
• 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 manada do host Arc/VM como uma credencial de nível de banco de dados no SQL Server 2025 (17.17.x), você deve habilitar a opção usando sp_configure com um usuário granted a permissão de nível de servidor ALTER SETTINGS.

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

SCHEMABINDING

Exibições criadas com SCHEMABINDING que fazem referência a um modelo externo (como uma instrução SELECT 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 Azure OpenAI usando a Identidade Gerenciada

Este exemplo cria um modelo externo do tipo EMBEDDINGS usando Azure OpenAI e usa Managed Identity para autenticação.

No SQL Server 2025 (17.x) e versões posteriores, você deve conectar seu SQL Server para Azure Arc e enável a identidade gerenciada primária.

Importante

Se você usar a Identidade Gerenciada com Azure OpenAI e SQL Server 2025 (17.x), a função Colaborador openAI dos ServiçosCognitivos deverá ser concedida à identidade gerenciada atribuída pelo sistema SQL Server habilitada pelo Azure Arc. Para obter mais informações, consulte o controle de acesso baseado em Role para Azure OpenAI em modelos Fábrica de IA do Azure.

Crie credenciais de acesso para 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/]
);

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

Este exemplo cria um modelo externo do tipo EMBEDDINGS usando Azure OpenAI e usa chaves de API 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 para 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

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 SQL Server.

Este exemplo orienta você pela configuração do SQL Server 2025 (17.x) com o ONNX Runtime para habilitar a geração de inserção de texto de IA local. Ele só se aplica a Windows.

Importante

Esse recurso requer que SQL Server Machine Learning Services esteja instalado.

Considerações de segurança

Você pode usar o recurso host do AI Runtime para configurar e usar suas próprias bibliotecas LLMs e ONNX com SQL Server. Como Microsoft não valida ou monitora modelos e bibliotecas de terceiros, você é responsável por selecionar modelos e bibliotecas apropriados, filtrar conteúdo, proteger o runtime e garantir a conformidade com quaisquer políticas e regulamentos aplicáveis.

Cuidado

Um modelo ONNX mal-intencionado ou comprometido pode exfiltrar dados ou executar código não autorizado. Use apenas modelos de fontes confiáveis e verificadas.

Para atenuar esses riscos, considere as seguintes práticas recomendadas de segurança:

• Implementar controles de acesso fortes: verifique se somente os usuários autorizados têm acesso a dados confidenciais e modelos de runtime onnx. Valide todos os modelos antes de carregá-los em SQL Server. Use o princípio de privilégios mínimos, bem como funções de banco de dados e privilégios.
• Monitorar e auditar o acesso: monitore e audite regularmente o acesso ao banco de dados e AI_GENERATE_EMBEDDINGS chamadas de função para detectar atividades suspeitas.
• Realize avaliações regulares de segurança: execute verificações de vulnerabilidade e revisões de segurança para identificar e reduzir possíveis riscos.

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

Execute o seguinte comando Transact-SQL (T-SQL) para habilitar os recursos de visualização do SQL Server 2025 (17.x) no banco de dados que você gostaria de usar para este 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 de SQL Server para armazenar os arquivos da biblioteca de runtime do 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 biblioteca tokenizers-cpp de 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 do seguinte link download 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 espaço reservado necessário para 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

• ALTER EXTERNAL MODEL (Transact-SQL)
• DROP EXTERNAL MODEL (Transact-SQL)
• AI_GENERATE_EMBEDDINGS (Transact-SQL)
• AI_GENERATE_CHUNKS (Transact-SQL)
• sys.external_models
• Criar e implantar um Azure OpenAI no recurso modelos de Fábrica de IA do Azure
• Opções de configuração do servidor
• controle de acesso baseado em Role para Azure OpenAI em modelos de Fábrica de IA do Azure