Bagikan melalui

BUAT MODEL EKSTERNAL (Transact-SQL)

Berlaku untuk: SQL Server 2025 (17.x) Database SQL Azure SQL databasedi Microsoft Fabric

Membuat objek model eksternal yang berisi lokasi, metode autentikasi, dan tujuan titik akhir inferensi model AI.

Sintaksis

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

Argumen

external_model_object_name

Menentukan nama yang ditentukan pengguna untuk model eksternal. Nama dalam database harus unik.

owner_name

Menentukan nama pengguna atau peran yang memiliki model eksternal. Jika Anda tidak menentukan argumen ini, pengguna saat ini menjadi pemiliknya. Bergantung pada izin dan peran, Anda mungkin perlu memberikan izin eksplisit kepada pengguna untuk menggunakan model eksternal tertentu.

TEMPAT

Menyediakan protokol konektivitas dan jalur ke titik akhir inferensi model AI.

API_FORMAT

Format pesan API untuk penyedia titik akhir inferensi model AI.

Nilai yang diterima adalah:

  • Azure OpenAI
  • OpenAI
  • Ollama
  • ONNX Runtime

Jenis Model

Jenis model yang diakses dari lokasi titik akhir inferensi model AI.

Nilai yang diterima adalah:

  • EMBEDDINGS

POLA

Model tertentu yang dihosting oleh penyedia AI. Misalnya, text-embedding-ada-002, text-embedding-3-large, atau o3-mini.

bukti sah

Menentukan DATABASE SCOPED CREDENTIAL objek yang digunakan dengan titik akhir inferensi model AI. Untuk informasi selengkapnya tentang jenis kredensial yang diterima dan aturan penamaan, lihat sp_invoke_external_rest_endpoint atau bagian Keterangan di artikel ini.

PARAMETER

String JSON valid yang berisi parameter runtime untuk ditambahkan ke pesan permintaan titik akhir inferensi model AI. Contohnya:

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH menentukan direktori pada instans SQL Server lokal tempat eksekusi ONNX Runtime berada.

Hak akses

Pembuatan dan perubahan model eksternal

ALTER ANY EXTERNAL MODEL Memerlukan izin database atau CREATE EXTERNAL MODEL .

Contohnya:

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

Atau:

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

Pemberian model eksternal

Untuk menggunakan model eksternal dalam fungsi AI, prinsipal harus diberikan kemampuan untuk EXECUTE itu.

Contohnya:

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

Jumlah Pengulangan

Jika panggilan penyematan mengalami kode status HTTP yang menunjukkan masalah sementara, Anda dapat mengonfigurasi permintaan untuk mencoba kembali secara otomatis. Untuk menentukan jumlah percobaan ulang, tambahkan JSON berikut ke PARAMETERS pada EXTERNAL MODEL. bilangan <number_of_retries> buletin antara nol (0) dan sepuluh (10), inklusif, dan tidak boleh NULL atau negatif.

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

Misalnya, untuk mengatur ke retry_count 3, gunakan string JSON berikut:

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

Coba lagi hitungan dengan parameter lain

Anda dapat menggabungkan jumlah percobaan ulang dengan parameter lain selama string JSON valid.

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

Komentar

HTTPS dan TLS

Untuk LOCATION parameter, hanya titik akhir inferensi model AI yang dikonfigurasi untuk menggunakan HTTPS dengan protokol enkripsi TLS yang didukung.

Format API dan jenis model yang diterima

Bagian berikut menguraikan format API yang diterima untuk setiap MODEL_TYPE.

API_FORMAT untuk EMBEDDINGS

Tabel ini menguraikan format API dan struktur titik akhir URL untuk EMBEDDINGS jenis model. Untuk melihat struktur payload tertentu, gunakan tautan di kolom Format API.

Format API Format jalur lokasi
Azure OpenAI https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI https://{server_name}/v1/penyematan
Ollama https://localhost:{port}/api/embed

Membuat titik akhir penyematan

Untuk informasi selengkapnya tentang membuat titik akhir penyematan, gunakan tautan ini untuk penyedia titik akhir inferensi model AI yang sesuai:

Aturan nama kredensial untuk model eksternal

Yang dibuat DATABASE SCOPED CREDENTIAL yang digunakan oleh model eksternal harus mengikuti aturan berikut:

  • Harus berupa URL yang valid

  • Domain URL harus menjadi salah satu domain yang disertakan dalam daftar yang diizinkan.

  • URL tidak boleh berisi string kueri

  • Protokol + Nama Domain yang Sepenuhnya Memenuhi Syarat (FQDN) dari URL yang disebut harus cocok dengan Protokol + FQDN dari nama kredensial

  • Setiap bagian dari jalur URL yang dipanggil harus sepenuhnya cocok dengan masing-masing bagian jalur URL dalam nama kredensial.

  • Kredensial harus mengarah ke jalur yang lebih umum daripada URL permintaan. Misalnya, kredensial yang dibuat untuk path https://northwind.azurewebsite.net/customers tidak dapat digunakan untuk URL https://northwind.azurewebsite.net.

Aturan nama kolase dan kredensial

RFC 3986 Bagian 6.2.2.1 menyatakan bahwa "Ketika URI menggunakan komponen sintaks generik, aturan kesetaraan sintaks komponen selalu berlaku; yaitu, bahwa skema dan tuan rumah tidak peka huruf besar/kecil." RFC 7230 Bagian 2.7.3 menyebutkan bahwa "semua yang lain dibandingkan dengan cara yang peka terhadap huruf besar/kecil."

Karena aturan kolase diatur di tingkat database, logika berikut berlaku untuk menjaga aturan kolase database dan aturan RFC tetap konsisten. (Aturan yang dijelaskan berpotensi lebih ketat daripada aturan RFC, misalnya jika database diatur untuk menggunakan kolase peka huruf besar/kecil.)

  1. Periksa apakah URL dan kredensial cocok menggunakan RFC, yang berarti:

    • Periksa skema dan host menggunakan kolater yang tidak peka huruf besar/kecil (Latin1_General_100_CI_AS_KS_WS_SC)
    • Periksa semua segmen URL lainnya dibandingkan dalam kolaset peka huruf besar/kecil (Latin1_General_100_BIN2)

  2. Periksa apakah URL dan kecocokan kredensial menggunakan aturan kolase database (dan tanpa melakukan pengodean URL apa pun).

Identitas yang dikelola

Untuk menggunakan identitas terkelola host Arc/VM sebagai kredensial tingkat database di SQL Server 2025 (17.x), Anda harus mengaktifkan opsi dengan menggunakan sp_configure dengan pengguna yang diberikan izin tingkat server ALTER SETTINGS.

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

SCHEMABINDING

Tampilan yang dibuat dengan SCHEMABINDING yang mereferensikan model eksternal (seperti SELECT pernyataan menggunakan AI_GENERATE_EMBEDDINGS) tidak dapat dihilangkan, dan Mesin Database memunculkan kesalahan. Untuk menghapus dependensi yang mereferensikan model eksternal, Anda harus terlebih dahulu memodifikasi atau menghapus definisi tampilan.

Tampilan katalog

Anda dapat melihat metadata model eksternal dengan mengkueri tampilan katalog sys.external_models . Anda harus memiliki akses ke model untuk melihat metadatanya.

SELECT *
FROM sys.external_models;

Contoh dengan titik akhir jarak jauh

Membuat MODEL EKSTERNAL dengan Azure OpenAI menggunakan Identitas Terkelola

Contoh ini membuat model eksternal dari jenis menggunakan EMBEDDINGS Azure OpenAI dan menggunakan Identitas Terkelola untuk autentikasi.

Di SQL Server 2025 (17.x) dan versi yang lebih baru, Anda harus menyambungkan SQL Server ke Azure Arc dan mengaktifkan identitas terkelola utama.

Penting

Jika Anda menggunakan Identitas Terkelola dengan Azure OpenAI dan SQL Server 2025 (17.x), peran Kontributor OpenAI Cognitive Services harus diberikan ke identitas terkelola yang ditetapkan sistem SQL Server yang diaktifkan oleh Azure Arc. Untuk informasi selengkapnya, lihat Kontrol akses berbasis peran untuk Azure OpenAI di Azure AI Foundry Models.

Buat kredensial akses ke Azure OpenAI menggunakan identitas terkelola:

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

Buat model eksternal:

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

Membuat model eksternal dengan Azure OpenAI menggunakan kunci dan parameter API

Contoh ini membuat model eksternal jenis menggunakan EMBEDDINGS Azure OpenAI dan menggunakan Kunci API untuk autentikasi. Contoh ini juga menggunakan PARAMETERS untuk mengatur parameter dimensi di titik akhir ke 725.

Buat kredensial akses ke Azure OpenAI menggunakan kunci:

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

Buat model eksternal:

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

Membuat MODEL EKSTERNAL dengan Ollama dan pemilik eksplisit

Contoh ini membuat model eksternal dari jenis menggunakan EMBEDDINGS Ollama yang dihosting secara lokal untuk tujuan pengembangan.

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

Membuat MODEL EKSTERNAL dengan OpenAI

Contoh ini membuat model eksternal dari jenis menggunakan EMBEDDINGS kredensial berbasis header OpenAI API_FORMAT dan HTTP untuk autentikasi.

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

Contoh dengan ONNX Runtime berjalan secara lokal

ONNX Runtime adalah mesin inferensi sumber terbuka yang memungkinkan Anda menjalankan model pembelajaran mesin secara lokal, menjadikannya ideal untuk mengintegrasikan kemampuan AI ke lingkungan SQL Server.

Contoh ini memandu Anda menyiapkan SQL Server 2025 (17.x) dengan ONNX Runtime untuk mengaktifkan pembuatan penyematan teks bertenaga AI lokal. Ini hanya berlaku pada Windows.

Penting

Fitur ini mengharuskan SQL Server Machine Learning Services diinstal.

Langkah 1: Mengaktifkan fitur pratinjau pengembang di SQL Server 2025

Jalankan perintah Transact-SQL (T-SQL) berikut untuk mengaktifkan fitur pratinjau SQL Server 2025 (17.x) dalam database yang ingin Anda gunakan untuk contoh ini:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

Langkah 2: Aktifkan runtime AI lokal di SQL Server 2025

Aktifkan runtime AI eksternal dengan menjalankan kueri T-SQL berikut:

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

Langkah 3: Siapkan pustaka ONNX Runtime

Buat direktori pada instans SQL Server untuk menyimpan file pustaka ONNX Runtime. Dalam contoh ini, C:\onnx_runtime digunakan.

Anda dapat menggunakan perintah berikut untuk membuat direktori:

cd C:\
mkdir onnx_runtime

Selanjutnya, unduh versi ONNX Runtime (1.19 atau lebih tinggi) yang sesuai untuk sistem operasi Anda. Setelah membuka zip unduhan, salin onnxruntime.dll (terletak di direktori lib) ke C:\onnx_runtime direktori yang dibuat.

Langkah 4: Siapkan pustaka tokenisasi

Unduh dan bangun tokenizers-cpp pustaka dari GitHub. Setelah dll dibuat, tempatkan tokenizer di C:\onnx_runtime direktori.

Nota

Pastikan dll yang dibuat diberi nama tokenizers_cpp.dll

Langkah 5: Unduh model ONNX

Mulailah dengan membuat model direktori di C:\onnx_runtime\.

cd C:\onnx_runtime
mkdir model

Contoh ini menggunakan all-MiniLM-L6-v2-onnx model, yang dapat diunduh dari Hugging Face.

Kloning repositori ke C:\onnx_runtime\model direktori dengan perintah git berikut:

Jika tidak diinstal, Anda dapat mengunduh git dari tautan unduhan berikut atau melalui winget (winget install Microsoft.Git)

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

Langkah 6: Mengatur izin direktori

Gunakan skrip PowerShell berikut untuk menyediakan akses pengguna MSSQLLaunchpad ke direktori ONNX Runtime:

$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

Langkah 7: Membuat model eksternal

Jalankan kueri berikut untuk mendaftarkan model ONNX Anda sebagai objek model eksternal:

Nilai 'PARAMETERS' yang digunakan di sini adalah placeholder yang diperlukan untuk 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 harus menunjuk ke direktori yang berisi model.onnx dan tokenizer.json file.
  • LOCAL_RUNTIME_PATH harus menunjuk ke direktori yang berisi onnxruntime.dll dan tokenizer_cpp.dll file.

Langkah 8: Hasilkan penyematan

Gunakan fungsi untuk ai_generate_embeddings menguji model dengan menjalankan kueri berikut:

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

Perintah ini meluncurkan AIRuntimeHost, memuat DLL yang diperlukan, dan memproses teks input.

Hasil dari kueri sebelumnya adalah array penyematan:

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

Aktifkan pencatatan sistem XEvent

Jalankan kueri berikut untuk mengaktifkan pengelogan sistem untuk pemecahan masalah.

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

Selanjutnya, gunakan kueri ini untuk melihat log sistem yang diambil:

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

Pembersihan

Untuk menghapus objek model eksternal, jalankan pernyataan T-SQL berikut:

DROP EXTERNAL MODEL myLocalOnnxModel;

Untuk menghapus izin direktori, jalankan perintah PowerShell berikut ini:

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

Terakhir, hapus C:/onnx_runtime direktori.

Konten terkait

  • Last updated on