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 de modelo de IA.

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 dentro do banco de dados.

owner_name

Especifica o nome do usuário ou função que possui o modelo externo. Se não especificar este argumento, o utilizador atual torna-se o proprietário. Dependendo das permissões e funções, pode ser necessário conceder permissão explícita aos utilizadores 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.

API_FORMAT

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

Os valores aceites são:

Azure OpenAI
OpenAI
Ollama
ONNX Runtime

Modelo_Tipo

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

Os valores aceites 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 aceites e regras de nomeação, consulte sp_invoke_external_rest_endpoint ou a secção de Observações deste artigo.

PARÂMETROS

Uma string JSON válida que contenha parâmetros de execução para adicionar à mensagem de pedido 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 se localizam os executáveis de tempo de execução ONNX.

Permissões

Criação e alteração de modelos externos

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

Por exemplo:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Ou:

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

Subvenções de modelo externo

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

Por exemplo:

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

Número de repetições

Se a chamada incorporada 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 tentativas, adicione o seguinte JSON ao PARAMETERS no EXTERNAL MODEL. 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 cadeia JSON:

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

Contagem de tentativas com outros parâmetros

Podes 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 encriptação TLS são suportados.

Formatos de API aceitos e tipos de modelo

As secções seguintes descrevem os formatos de API aceites para cada MODEL_TYPE.

API_FORMAT para EMBEDDINGS

Esta tabela descreve os formatos da API e as estruturas de endpoint URL para o EMBEDDINGS tipo de modelo. Para visualizar estruturas de carga útil específicas, use o link na coluna Formato da API.

Formato da API	Formato do caminho de localização
Azure OpenAI	https://{endpoint}/openAI/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	Disponível em: https://{server_name}/v1/embeddings
Ollama	https://localhost:{port}/api/embed

Criar pontos de extremidade de incorporação

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

Regras de nome de credencial para modelos externos

O modelo 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 dos domínios incluídos na lista de autorizações.
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 a Protocolo + FQDN do nome da credencial
Cada parte do caminho da URL chamada deve corresponder completamente à respetiva parte do caminho da URL no nome da credencial.
A credencial deve apontar para um caminho mais genérico do que o 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 agrupamento e nome de credenciais

A Secção 6.2.2.1 do RFC 3986 afirma que "Quando um URI utiliza componentes da sintaxe genérica, as regras de equivalência da sintaxe dos componentes aplicam-se sempre; nomeadamente, que o esquema e o anfitrião são indiferentes a maiúsculas e minúsculas." A Secção 2.7.3 do RFC 7230 menciona que "todas as outras são comparadas de forma sensível a maiúsculas e maiúsculas."

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

Verifique se a URL e a credencial correspondem usando a RFC, o que significa:
- Verifique o esquema e o host usando um agrupamento 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)
Verifique se a URL e a credencial correspondem usando as regras de agrupamento de banco de dados (e sem fazer nenhuma codificação de URL).

Identidade gerenciada

Para usar a identidade gerida do anfitrião Arc/VM como credencial ao nível da base de dados no SQL Server 2025 (17.x), deve ativar a opção usando sp_configure com um utilizador que receba a permissão ALTER SETTINGS ao nível do servidor.

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

SCHEMABINDING

As vistas criadas com SCHEMABINDING isso referem-se a um modelo externo (como uma SELECT instrução usando AI_GENERATE_EMBEDDINGS) não podem ser eliminadas, e o Motor de Base de Dados gera um erro. Para remover dependências que referenciam um modelo externo, deve primeiro modificar ou eliminar a definição de vista.

Vista de catálogo

Pode visualizar metadados externos de modelos consultando a vista de catálogo sys.external_models . Deve ter acesso a um modelo para visualizar os 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 Gerida para autenticação.

No SQL Server 2025 (17.x) e versões posteriores, deve ligar o seu SQL Server ao Azure Arc e ativar a identidade gerida principal.

Importante

Se utilizar Identidade Gerida com Azure OpenAI e SQL Server 2025 (17.x), o papel de Contribuidor OpenAI de Serviços Cognitivos deve ser atribuído à identidade gerida atribuída ao sistema do SQL Server habilitada pelo Azure Arc. Para mais informações, veja Controlo de acesso baseado em papéis para Azure OpenAI em Azure AI Foundry Models.

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

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 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 dimensions 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}'
);

Crie um MODELO EXTERNO com 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'
);

Crie um MODELO EXTERNO com OpenAI

Este exemplo cria um modelo externo do EMBEDDINGS tipo usando as credenciais baseadas em cabeçalhos 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 a correr localmente

O ONNX Runtime é um mecanismo de inferência de código aberto que permite executar modelos de aprendizado de máquina localmente, tornando-o ideal para integrar recursos de IA em ambientes SQL Server.

Este exemplo orienta-o na configuração do SQL Server 2025 (17.x) com o ONNX Runtime para permitir a geração local de embedding de texto alimentada por IA. Aplica-se apenas ao Windows.

Importante

Esse recurso requer que os Serviços de Aprendizado de Máquina do SQL Server estejam instalados.

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

Execute o seguinte comando Transact-SQL (T-SQL) para ativar funcionalidades de pré-visualização do SQL Server 2025 (17.x) na base de dados que pretende usar neste exemplo:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Etapa 2: Habilitar o tempo de execução da IA local no SQL Server 2025

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

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

Passo 3: Configurar a biblioteca ONNX Runtime

Crie um diretório na instância do SQL Server para armazenar os ficheiros da biblioteca ONNX Runtime. Neste exemplo, C:\onnx_runtime é usado.

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

cd C:\
mkdir onnx_runtime

De seguida, descarregue uma versão do ONNX Runtime (1.19 ou superior) que seja adequada ao seu sistema operativo. 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 tokenização

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

Observação

Verifique se a dll criada tem o nometokenizers_cpp.dll

Passo 5: Faça o download do 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ê pode baixar o git a partir do seguinte link de download ou via 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 utilizador 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 registar o 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 ficheiros.
LOCAL_RUNTIME_PATH deve apontar para o diretório que contém onnxruntime.dll e tokenizer_cpp.dll ficheiros.

Etapa 8: Gerar incorporaçõ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);

Este comando inicia o AIRuntimeHost, carregue as DLLs 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...]

Ativar o registo do sistema XEvent

Execute a seguinte consulta para ativar o registo 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

De seguida, use esta consulta para ver os registos 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

Finalmente, exclua o C:/onnx_runtime diretório.

Comentários

Esta página foi útil?

Last updated on 2025-12-08