DıŞ MODEL OLUŞTURMA (Transact-SQL)

Applies to: SQL Server 2025 (17.x) Azure SQL DatabaseAzure SQL Managed InstanceSQL Microsoft Fabric< veritabanı>

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.

Uyarı

CREATE EXTERNAL MODEL, Always-up-to-dateupdate ilkesi ile Azure SQL Managed Instance kullanılabilir.

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, ONNX Çalışma Zamanı yürütülebilir dosyalarının bulunduğu yerel SQL Server örneğindeki dizini belirtir.

İ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'te (17.x) veritabanı düzeyi kimlik bilgisi olarak Arc/VM konağı managed identity kullanmak için seçeneği sp_configure kullanarak ALTER SETTINGS sunucu düzeyinde izin olan bir kullanıcıyla etkinleştirmeniz gerekir.

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

SCHEMABINDING

Dış modele (SCHEMABINDING kullanan bir SELECT deyimi gibi) başvuran AI_GENERATE_EMBEDDINGS ile oluşturulan görünümler bırakılamaz ve Database Engine bir 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 EMBEDDINGS türünün dış 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 Azure Arc ve birincil yönetilen kimliği bağlamanız gerekir.

Önemli

Azure OpenAI ve SQL Server 2025 (17.x) ile Yönetilen Kimlik kullanıyorsanız, Cognitive Services OpenAI Katkıda Bulunanı rolü SQL Server sistem tarafından atanan yönetilen kimliğine Azure Arc tarafından etkinleştirilmelidir. Daha fazla bilgi için bkz. Azure AI Foundry Models Azure OpenAI için Role tabanlı erişim denetimi.

Yönetilen kimlik kullanarak OpenAI'yi Azure için 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ını ve parametrelerini kullanarak Azure OpenAI ile dış model oluşturma

Bu örnek, Azure OpenAI kullanarak EMBEDDINGS türünün dış modelini oluşturur ve kimlik doğrulaması için API Anahtarlarını kullanır. Örnek ayrıca uç noktadaki dimensions parametresini 725 olarak ayarlamak için kullanır PARAMETERS .

Anahtar kullanarak OpenAI'yi Azure için erişim kimlik bilgileri 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 EMBEDDINGS ve HTTP başlığı tabanlı kimlik bilgilerini kullanarak türde API_FORMAT 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ızı sağlayan ve yapay zeka özelliklerini SQL Server ortamlarla tümleştirmek için ideal hale getiren bir açık kaynak çıkarım altyapısıdır.

Bu örnek, yerel yapay zeka destekli metin ekleme oluşturma özelliğini etkinleştirmek için ONNX Runtime ile SQL Server 2025 (17.x) ayarlama işleminde size yol gösterir. Yalnızca Windows için geçerlidir.

Önemli

Bu özellik, SQL Server Machine Learning Services yüklenmesini gerektirir.

Güvenlik konuları

SQL Server ile kendi LLM'lerinizi ve ONNX kitaplıklarınızı yapılandırmak ve kullanmak için AI Çalışma Zamanı Konağı özelliğini kullanabilirsiniz. Microsoft üçüncü taraf modelleri ve kitaplıkları doğrulamadığından veya izlemediğinden, uygun modelleri ve kitaplıkları seçmek, içeriği filtrelemek, çalışma zamanının güvenliğini sağlamak ve geçerli ilke ve düzenlemelere uyumluluğu sağlamak sizin sorumluluğundadır.

Dikkat

Kötü amaçlı veya güvenliği aşılmış bir ONNX modeli verileri dışarı alabilir veya yetkisiz kod yürütebilir. Yalnızca güvenilir, doğrulanmış kaynaklardan modelleri kullanın.

Bu riskleri azaltmak için aşağıdaki en iyi güvenlik uygulamalarını göz önünde bulundurun:

  • Güçlü erişim denetimleri uygulama: Yalnızca yetkili kullanıcıların hassas verilere ve ONNX Çalışma Zamanı modellerine erişebildiğinden emin olun. Tüm modelleri SQL Server yüklemeden önce doğrulayın. en az ayrıcalık ilkesinin yanı sıra veritabanı rollerini ve ayrıcalıklarınıkullanın.
  • Erişimi izleme ve denetleme: Şüpheli etkinlikleri algılamak için veritabanına ve AI_GENERATE_EMBEDDINGS işlev çağrılarına erişimi düzenli olarak izleyip denetleyebilirsiniz.
  • Düzenli güvenlik değerlendirmeleri yapma: Olası riskleri belirlemek ve azaltmak için güvenlik açığı taramaları ve güvenlik gözden geçirmeleri gerçekleştirin.

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

Bu örnekte 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ı kitaplık dosyalarını tutmak için 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

>tokenizers-cpp kitaplığı GitHub 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 download bağlantısından veya winget (winget install Microsoft) aracılığıyla indirebilirsiniz. Git)

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

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