Aracılığıyla paylaş

HARICI MODEL OLUŞTUR (Transact-SQL)

Şunlar için geçerlidir: SQL Server 2025 (17.x) Azure SQL DatabaseSQL database in Microsoft Fabric

Yapay zeka modeli çıkarım uç noktasının konumunu, kimlik doğrulama yöntemini ve amacını içeren bir dış model nesnesi oluşturur.

Sözdizimi

Transact-SQL söz dizimi kuralları

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' ]
  );

Tartışmalar

external_model_object_name

Dış model için kullanıcı tanımlı adı belirtir. Adın veritabanında benzersiz olması gerekir.

owner_name

Dış modelin sahibi olan kullanıcının veya rolün adını belirtir. Bu argümanı belirtmezseniz, mevcut kullanıcı sahibi olur. İzinlere ve rollere bağlı olarak, kullanıcılara belirli harici modelleri kullanmaları için açık izin vermeniz gerekebilir.

KONUM

Bağlantı protokolunu ve yapay zeka modeli çıkarım uç noktasının yolunu sağlar.

API_FORMAT

Yapay zeka modeli çıkarım uç noktası sağlayıcısı için API ileti biçimi.

Kabul edilen değerler şunlardır:

  • Azure OpenAI
  • OpenAI
  • Ollama
  • ONNX Runtime

MODEL_TİPİ

Yapay zeka modelinden erişilen model türü, çıkarım nokta konumu.

Kabul edilen değerler şunlardır:

  • EMBEDDINGS

Model

Yapay zeka sağlayıcısı tarafından barındırılan model. Örneğin, text-embedding-ada-002, text-embedding-3-large veya o3-mini.

YETKİ BELGESİ

AI model çıkarım uç noktasında kullanılan nesneyi belirtir DATABASE SCOPED CREDENTIAL . Kabul edilen kimlik türleri ve adlandırma kuralları hakkında daha fazla bilgi için sp_invoke_external_rest_endpoint veya bu makalenin Açıklamalar bölümüne bakınız.

PARAMETRE

AI modeli çıkarım uç noktası isteği mesajına eklenecek çalışma zamanı parametreleri içeren geçerli bir JSON dizisi. Örneğin:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH yerel SQL Server örneğinde ONNX Çalışma Zamanı çalıştırılabilir dosyalarının bulunduğu dizini belirler.

İzinler

Dış model oluşturma ve değiştirme

ALTER ANY EXTERNAL MODEL veya CREATE EXTERNAL MODEL veritabanı izni gerektirir.

Örneğin:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Veya:

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

Dış model izinleri

Yapay zeka işlevinde dış model kullanmak için bir sorumluya EXECUTE bu özellik verilmelidir.

Örneğin:

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

Yeniden deneme sayısı

Ekleme çağrısı geçici sorunları belirten HTTP durum kodlarıyla karşılaşırsa, isteği otomatik olarak yeniden deneyecek şekilde yapılandırabilirsiniz. Yeniden deneme sayısını belirtmek için öğesine aşağıdaki JSON'ı PARAMETERSEXTERNAL MODELekleyin. <number_of_retries> sıfır () ile on (010 ) () arasında bir tamsayı olmalıdır ve bu sayı negatif veya negatif olamazNULL.

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

Örneğin, 3'e retry_count ayarlamak için aşağıdaki JSON dizisi kullanılır:

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

Diğer parametrelerle yeniden deneme sayısı

JSON dizisi geçerli olduğu sürece tekrar deneme sayısını diğer parametrelerle birleştirebilirsiniz.

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

Açıklamalar

HTTPS ve TLS

Parametre LOCATION için, yalnızca TLS şifreleme protokolüyle HTTPS kullanacak şekilde yapılandırılmış yapay zeka model çıkarım uç noktaları desteklenir.

Kabul edilen API biçimleri ve model türleri

Aşağıdaki bölümler, her biri MODEL_TYPEiçin kabul edilen API formatlarını özetlemektedir.

EMBEDDINGS için API_FORMAT

Bu tablo, model tipi için EMBEDDINGS API formatlarını ve URL uç nokta yapılarını özetler. Belirli yük yapılarını görüntülemek için API Biçimi sütunundaki bağlantıyı kullanın.

API biçimi Konum yolu biçimi
Azure OpenAI https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI https://{server_name}/v1/embeddings
Ollama https://localhost:{port}/api/embed

Ekleme uç noktaları oluşturma

Ekleme uç noktaları oluşturma hakkında daha fazla bilgi için uygun yapay zeka modeli çıkarım uç noktası sağlayıcısı için şu bağlantıları kullanın:

Dış model için kimlik adı kuralları

Harici bir model tarafından oluşturulan DATABASE SCOPED CREDENTIAL model şu kurallara uymalıdır:

  • Geçerli bir URL olmalıdır

  • URL alan adı, izin listesinde yer alan alan adlarından biri olmalıdır.

  • URL bir sorgu dizesi içermemelidir

  • Çağrılan URL'nin Protokol + Tam Etki Alanı Adı (FQDN), kimlik bilgisi adının Protokol + FQDN değeriyle eşleşmelidir

  • Çağrılan URL yolunun her bölümü, kimlik adındaki URL yolunun ilgili kısmıyla tamamen eşleşmelidir.

  • Kimlik bilgisi, istek URL'sinden daha genel bir yola işaret etmelidir. Örneğin, yol https://northwind.azurewebsite.net/customers için oluşturulan bir kimlik bilgisi URL https://northwind.azurewebsite.netiçin kullanılamaz.

Harmanlama ve kimlik bilgisi adı kuralları

RFC 3986 Bölüm 6.2.2.1 şöyle der: "Bir URI genel sözdiziminin bileşenlerini kullandığında, bileşen sözdizimi eşdeğerlik kuralları her zaman geçerlidir; yani, şema ve ev sahibi çok küçük harf duyarsız olsun." RFC 7230 Bölüm 2.7.3 , "diğer tüm unsurların çok küçük harf hassasiyetli şekilde karşılaştırıldığını" belirtir.

Veritabanı düzeyinde bir derleme kuralı belirlendiğinden, veritabanı derleme kuralı ile RFC kurallarının tutarlı kalması için aşağıdaki mantık geçerlidir. (Tanımlanan kural, örneğin veritabanı büyük harf duyarlı bir derleme kullanacak şekilde ayarlanmışsa, RFC kurallarından daha kısıtlayıcı olabilir.)

  1. RFC kullanarak URL ve kimlik bilgilerinin eşleşip eşleşmediğini denetleyin, yani:

    • Büyük/küçük harfe duyarlı olmayan harmanlama (Latin1_General_100_CI_AS_KS_WS_SC) kullanarak düzeni ve konağı denetleyin
    • URL'nin diğer tüm kesimlerinin büyük/küçük harfe duyarlı harmanlamada (Latin1_General_100_BIN2) karşılaştırılmasını denetleyin

  2. Veritabanı harmanlama kurallarını kullanarak (ve URL kodlaması yapmadan) URL'nin ve kimlik bilgilerinin eşleşip eşleşmediğini denetleyin.

İdare edilen kimlik

SQL Server 2025 (17.x)'de Arc/VM hostunun yönetilen kimliğini veritabanı düzeyinde bir kimlik doğrulaması olarak kullanmak için, ALTER SETTINGS sunucu düzeyinde izni verilen bir kullanıcıyla bu seçeneği sp_configure etkinleştirmeniz gerekir.

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

SCHEMABINDING

Bu harici modele (örneğin SELECT bir ifade kullanılarak AI_GENERATE_EMBEDDINGS) referansla oluşturulan SCHEMABINDING görünümler kaldırılamaz ve Veritabanı Motoru hata oluşturur. Dış modele referans veren bağımlılıkları kaldırmak için önce görünüm tanımını değiştirmek veya kaldırmak gerekir.

Katalog görünümü

sys.external_models katalog görünümünü sorgulaarak harici model meta verilerini görebilirsiniz. Meta verilerini görmek için bir modele erişiminiz olmalıdır.

SELECT *
FROM sys.external_models;

Uzak uç noktalarla ilgili örnekler

Yönetilen Kimlik kullanarak Azure OpenAI ile EXTERNAL MODEL oluşturma

Bu örnek, Azure OpenAI kullanarak bu EMBEDDINGS tipin harici bir modelini oluşturur ve kimlik doğrulaması için Managed Identity kullanır.

SQL Server 2025 (17.x) ve sonraki sürümlerde, SQL Server'ınızı Azure Arc'a bağlamalı ve birincil yönetilen kimliği etkinleştirmelisiniz.

Önemli

Azure OpenAI ve SQL Server 2025 (17.x) ile Yönetilen Kimlik kullanıyorsanız, Cognitive Services OpenAI Katkıcı rolü, Azure Arc tarafından etkinleştirilen SQL Server'ın sistem tarafından atanan yönetilen kimliğine verilmelidir. Daha fazla bilgi için Azure AI Foundry Models'te Azure OpenAI için Rol tabanlı erişim kontrolü sayfasına bakınız.

Azure OpenAI'ye yönetilen bir kimlik kullanarak erişim kimlik bilgileri oluşturun:

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

Dış modeli oluşturun:

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/]
);

API anahtarları ve parametreleri kullanarak Azure OpenAI ile harici bir model oluşturun

Bu örnek, Azure OpenAI kullanarak bu EMBEDDINGS tipin harici bir modelini oluşturur ve kimlik doğrulama için API Anahtarları kullanır. Örnek ayrıca uç noktadaki dimensions parametresini 725 olarak ayarlamak için kullanır PARAMETERS .

Bir anahtar kullanarak Azure OpenAI'ye erişim credentialları oluşturun:

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

Dış modeli oluşturun:

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

Ollama ve açık bir sahip ile EXTERNAL MODEL oluşturma

Bu örnek, geliştirme amaçları için yerel olarak barındırılan Ollama kullanılarak harici EMBEDDINGS bir model oluşturur.

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

OpenAI ile EXTERNAL MODEL oluşturma

Bu örnek, kimlik doğrulama için OpenAI API_FORMAT ve HTTP başlığı tabanlı kimlik bilgilerini kullanarak türde EMBEDDINGS harici bir model oluşturur.

-- 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]
);

ONNX Çalışma Zamanının yerel olarak çalıştığı bir örnek

ONNX Runtime , makine öğrenmesi modellerini yerel olarak çalıştırmanıza olanak tanıyan bir açık kaynak çıkarım altyapısıdır ve yapay zeka özelliklerini SQL Server ortamlarıyla tümleştirmek için idealdir.

Bu örnek, SQL Server 2025 (17.x) kurmayı ONNX Runtime ile kurarken yerel yapay zeka destekli metin gömme üretimini etkinleştirir. Yalnızca Windows için geçerlidir.

Önemli

Bu özellik , SQL Server Machine Learning Services'ın yüklü olmasını gerektirir.

1. Adım: SQL Server 2025'te geliştirici önizleme özelliklerini etkinleştirme

Bu örnek için kullanmak istediğiniz veritabanında SQL Server 2025 (17.x) önizleme özelliklerini etkinleştirmek için aşağıdaki Transact-SQL (T-SQL) komutunu çalıştırın:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

2. Adım: SQL Server 2025'te yerel yapay zeka çalışma zamanını etkinleştirme

Aşağıdaki T-SQL sorgusunu çalıştırarak harici yapay zeka çalışma zamanlarını etkinleştirin:

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

Adım 3: ONNX Çalışma Zamanı kütüphanesini kurun

ONNX Çalışma Zamanı kütüphane dosyalarını tutacak SQL Server örneğinde bir dizin oluşturun. Bu örnekte C:\onnx_runtime kullanılmıştır.

Dizini oluşturmak için aşağıdaki komutları kullanabilirsiniz:

cd C:\
mkdir onnx_runtime

Sonra, işletim sisteminize uygun bir ONNX Runtime sürümünü (1.19 veya üzeri) indirin. İndirmenin sıkıştırmasını kaldırdıktan sonra dosyasını (lib dizininde bulunur) oluşturulan dizine onnxruntime.dll kopyalayın C:\onnx_runtime .

4. Adım: Belirteç oluşturma kitaplığını ayarlama

GitHub'dan tokenizers-cpp kitaplığı indirin ve derleyin. Dll oluşturulduktan sonra belirteci dizinine C:\onnx_runtime yerleştirin.

Uyarı

Oluşturulan dll dosyasının tokenizers_cpp.dll olarak adlandırılmasını sağlayın

5. Adım: ONNX modelini indirme

dizinini model içinde C:\onnx_runtime\oluşturarak başlayın.

cd C:\onnx_runtime
mkdir model

Bu örnekte, all-MiniLM-L6-v2-onnx indirilebilen model kullanılır.

Aşağıdaki C:\onnx_runtime\model komutuyla depoyu dizine kopyalayın:

Yüklü değilse, git'i aşağıdaki indirme bağlantısından veya winget aracılığıyla indirebilirsiniz (winget Microsoft.Git'i yükleyin)

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

6. Adım: Dizin izinlerini ayarlama

MSSQLLaunchpad kullanıcısına ONNX Çalışma Zamanı dizinine erişim sağlamak için aşağıdaki PowerShell betiklerini kullanın:

$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

7. Adım: Dış modeli oluşturma

ONNX modelinizi harici model nesnesi olarak kaydetmek için aşağıdaki sorguyu çalıştırın:

Burada kullanılan 'PARAMETERS' değeri, SQL Server 2025 (17.x) için gereken bir yer tutucudur.

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 ve dosyalarını içeren model.onnxtokenizer.json dizine işaret etmeli.
  • LOCAL_RUNTIME_PATH ve dosyaları onnxruntime.dlltokenizer_cpp.dll içeren dizine işaret etmeli.

8. Adım: Eklemeler oluşturma

Modeli test etmek için aşağıdaki sorguyu çalıştırarak bu ai_generate_embeddings fonksiyonu kullanın:

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

Bu komut AIRuntimeHost, gerekli DLL'leri yükler ve giriş metnini işler.

Önceki sorgudan elde edilen bir gömme dizisi ortaya çıktı:

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

XEvent sistem kaydını etkinleştir

Sorun giderme için sistem kaydını etkinleştirmek için aşağıdaki sorguyu çalıştırın.

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

Sonra, bu sorguyu kullanarak ele geçirilen sistem kayıtlarına bakın:

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);

Temizleme

Harici model nesnesini kaldırmak için aşağıdaki T-SQL ifadesini çalıştırın:

DROP EXTERNAL MODEL myLocalOnnxModel;

Dizin izinlerini kaldırmak için aşağıdaki PowerShell komutlarını çalıştırın:

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

Son olarak, dizini silin C:/onnx_runtime .

İlgili içerik

  • Last updated on