CREATE EXTERNAL MODEL(Transact-SQL)

2025-08-21

적용 대상: SQL Server 2025(17.x) 미리 보기

AI 모델 유추 엔드포인트의 위치, 인증 방법 및 용도를 포함하는 외부 모델 개체를 만듭니다.

문법

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

주장들

external_model_object_name

외부 모델의 사용자 정의 이름을 지정합니다. 이름은 반드시 데이터베이스 내에서 고유해야 합니다.

owner_name

외부 모델을 소유하는 사용자 또는 역할의 이름을 지정합니다. 지정하지 않으면 현재 사용자에게 소유권이 부여됩니다. 사용 권한 및 역할에 따라 특정 외부 모델을 사용하려면 사용자에게 명시적 권한을 부여해야 합니다.

위치

AI 모델 유추 엔드포인트에 대한 연결 프로토콜 및 경로를 제공합니다.

API_FORMAT

AI 모델 유추 엔드포인트 공급자에 대한 API 메시지 형식입니다.

허용되는 값은 다음과 같습니다.

Azure OpenAI
OpenAI
Ollama
ONNX Runtime

모델 유형

AI 모델 유추 엔드포인트 위치에서 액세스되는 모델의 유형입니다.

허용되는 값은 다음과 같습니다.

EMBEDDINGS

모델

AI 공급자가 호스트하는 특정 모델입니다. 예를 들어 text-embedding-ada-002, text-embedding-3-large 또는 o3-mini입니다.

자격 증명

DATABASE SCOPED CREDENTIAL AI 모델 유추 엔드포인트에 사용되는 개체를 나타냅니다. 허용되는 자격 증명 유형 및 명명 규칙에 대한 자세한 내용은 sp_invoke_external_rest_endpoint 또는 이 문서의 설명 섹션에서 찾을 수 있습니다.

매개 변수

AI 모델 유추 엔드포인트 요청 메시지에 추가할 런타임 매개 변수를 포함하는 유효한 JSON 문자열입니다. 다음은 그 예입니다.

'{ "dimensions": 1536 }'

LOCAL_RUNTIME_PATH

LOCAL_RUNTIME_PATH 는 ONNX 런타임 실행 파일이 있는 로컬 SQL Server의 디렉터리를 지정합니다.

권한

외부 모델 만들기 및 변경

ALTER ANY EXTERNAL MODEL CREATE EXTERNAL MODEL 데이터베이스 사용 권한이 필요합니다.

다음은 그 예입니다.

GRANT CREATE EXTERNAL MODEL TO [<PRINCIPAL>];

또는

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

외부 모델 부여

AI 함수에서 외부 모델을 사용하려면 보안 주체에게 해당 기능을 EXECUTE 부여해야 합니다.

다음은 그 예입니다.

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

재시도 횟수

embeddings 호출에 임시 문제를 나타내는 HTTP 상태 코드가 발생하면 요청을 자동으로 다시 시도하도록 구성할 수 있습니다. 재시도 횟수를 지정하려면 다음 JSON을 on에 PARAMETERSEXTERNAL MODEL추가합니다. 0<number_of_retries>()과 100(10) 사이의 정수여야 하며 포함되며 음수일 수 없습니다NULL.

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

예를 들어 3으로 설정 retry_count 하려면 다음 JSON 문자열을 작성합니다.

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

다른 매개 변수를 사용하여 재시도 횟수

재시도 횟수는 유효한 JSON 문자열인 경우 다른 매개 변수와 결합할 수도 있습니다.

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

비고

HTTPS 및 TLS

TLS 암호화 프로토콜과 함께 HTTPS를 사용하도록 구성된 AI 모델 유추 엔드포인트만 매개 변수에 LOCATION 대해 지원됩니다.

허용되는 API 형식 및 모델 형식

다음 섹션에서는 각 MODEL_TYPEAPI 형식에 대해 허용되는 API 형식을 간략하게 설명합니다.

EMBEDDINGS에 대한 API_FORMAT

이 표에서는 모델 형식에 대한 API 형식 및 URL 엔드포인트 구조를 간략하게 EMBEDDINGS 설명합니다. 특정 페이로드 구조를 보려면 API 형식 열의 링크를 사용합니다.

API 형식	위치 경로 형식
Azure OpenAI	https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version={date}
OpenAI	https://{server_name}/v1/embeddings
올라마 섬	https://localhost:{port}/api/embed

포함 엔드포인트 만들기

포함 엔드포인트를 만드는 방법에 대한 자세한 내용은 적절한 AI 모델 유추 엔드포인트 공급자에 대해 다음 링크를 사용합니다.

EXTERNAL MODEL에 대한 자격 증명 이름 규칙

만든 DATABASE SCOPED CREDENTIALEXTERNAL MODEL 내용은 다음 특정 규칙을 준수해야 합니다.

유효한 URL이어야 합니다.
URL 도메인은 허용 목록에 포함된 도메인 중 하나여야 합니다.
URL에 쿼리 문자열이 포함되어서는 안됩니다.
호출된 URL의 프로토콜 + FQDN(정규화된 도메인 이름)은 자격 증명 이름의 프로토콜 + FQDN과 일치해야 합니다.
호출된 URL 경로의 각 부분은 자격 증명 이름에 있는 URL 경로의 각 부분과 완전히 일치해야 합니다.
자격 증명은 요청 URL보다 더 일반적인 경로를 가리킵니다. 예를 들어 경로 https://northwind.azurewebsite.net/customers 에 대해 만든 자격 증명은 URL에 사용할 수 없습니다. https://northwind.azurewebsite.net

데이터 정렬 및 자격 증명 이름 규칙

RFC 3986 섹션 6.2.2.1 은 "URI가 제네릭 구문의 구성 요소를 사용하는 경우 구성 요소 구문 동등 규칙이 항상 적용됩니다. 즉, 체계와 호스트는 대/소문자를 구분하지 않습니다." RFC 7230 섹션 2.7.3 은 "다른 모든 항목은 대/소문자를 구분하는 방식으로 비교된다"고 언급합니다.

데이터베이스 수준에서 데이터 정렬 규칙이 설정되어 있으므로 데이터베이스 데이터 정렬 규칙 및 앞에서 언급한 RFC와 일관성을 유지하도록 다음 논리가 적용됩니다. (예를 들어 데이터베이스가 대/소문자를 구분하는 데이터 정렬을 사용하도록 설정된 경우 설명된 규칙은 RFC 규칙보다 더 제한적일 수 있습니다.)

RFC를 사용하여 URL 및 자격 증명이 일치하는지 확인합니다. 즉, 다음을 의미합니다.
- 대/소문자를 구분하지 않는 데이터 정렬을 사용하여 구성표 및 호스트 확인(Latin1_General_100_CI_AS_KS_WS_SC)
- URL의 다른 모든 세그먼트가 대/소문자를 구분하는 데이터 정렬에서 비교되는지 확인합니다(Latin1_General_100_BIN2).
URL 및 자격 증명이 데이터베이스 데이터 정렬 규칙을 사용하여 일치하는지 확인합니다(URL 인코딩을 수행하지 않고).

관리되는 식별

SQL Server 2025에서 인증에 관리 ID를 사용하려면 sp_configure 사용자와 함께 옵션을 사용하도록 설정해야 합니다.

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

스키마바인딩

데이터베이스 엔진에서 오류를 발생시키는 SCHEMABINDING 경우(예: EXTERNAL MODEL 문을 사용하여SELECT) 만든 AI_GENERATE_EMBEDDINGS 뷰를 삭제하고 참조할 수 없습니다. 뷰 정의 자체를 먼저 수정하거나 삭제하여 참조하는 EXTERNAL MODEL종속성을 제거해야 합니다.

카탈로그 뷰

카탈로그 뷰를 쿼리하여 외부 모델 메타데이터를 sys.external_models 볼 수 있습니다. 메타데이터를 보려면 모델에 대한 액세스 권한이 있어야 합니다.

SELECT * FROM sys.external_models;

원격 엔드포인트가 있는 예제

관리 ID를 사용하여 Azure OpenAI로 EXTERNAL MODEL 만들기

이 예제에서는 Azure OpenAI를 EXTERNAL MODEL 사용하여 형식을 EMBEDDINGS 만들고 인증에 관리 ID 를 사용합니다.

중요합니다

Azure OpenAI 및 SQL Server 2025에서 관리 ID를 사용하는 경우 Azure Arc에서 사용하도록 설정된 SQL Server의 시스템 할당 관리 ID에 Cognitive Services OpenAI 기여자 역할을 부여해야 합니다. 자세한 내용은 Azure AI Foundry 모델에서 Azure OpenAI에 대한 역할 기반 액세스 제어를 참조하세요.

-- Create access credentials to Azure OpenAI using a managed identity:
CREATE DATABASE SCOPED CREDENTIAL [https://my-azure-openai-endpoint.openai.azure.com/]
    WITH IDENTITY = 'Managed Identity', secret = '{"resourceid":"https://cognitiveservices.azure.com"}';
GO

-- Create the EXTERNAL MODEL
CREATE EXTERNAL MODEL MyAzureOpenAiModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.openai.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.openai.azure.com/]
);

API 키 및 매개 변수를 사용하여 Azure OpenAI로 EXTERNAL MODEL 만들기

이 예제에서는 Azure OpenAI를 EXTERNAL MODEL 사용하여 형식을 EMBEDDINGS 만들고 인증에 API 키를 사용합니다. 또한 이 예제에서는 엔드포인트의 차원 매개 변수를 725로 설정하는 데도 사용합니다 PARAMETERS .

-- Create access credentials to Azure OpenAI using a key:
CREATE DATABASE SCOPED CREDENTIAL [https://my-azure-openai-endpoint.openai.azure.com/]
    WITH IDENTITY = 'HTTPEndpointHeaders', secret = '{"api-key":"YOUR_AZURE_OPENAI_KEY"}';
GO

-- Create the EXTERNAL MODEL
CREATE EXTERNAL MODEL MyAzureOpenAiModel
AUTHORIZATION CRM_User
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.openai.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.openai.azure.com/],
      PARAMETERS = '{"dimensions":725}'
);

Ollama 및 명시적 소유자를 사용하여 EXTERNAL MODEL 만들기

이 예제에서는 개발 목적으로 로컬로 EXTERNAL MODEL 호스트되는 Ollama를 사용하여 형식을 EMBEDDINGS 만듭니다.

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

OpenAI를 사용하여 EXTERNAL MODEL 만들기

이 예제에서는 인증을 EXTERNAL MODEL 위해 OpenAI EMBEDDINGS 및 HTTP 헤더 기반 자격 증명을 사용하여 형식을 만듭니다API_FORMAT.

-- 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 런타임을 사용하는 예제

이 예제에서는 로컬 AI 기반 텍스트 포함 생성을 사용하도록 설정하기 위해 ONNX 런타임을 사용하여 SQL Server 2025를 설정하는 방법을 안내합니다. Windows에서만 적용됩니다.

ONNX 런타임 은 로컬에서 기계 학습 모델을 실행할 수 있는 오픈 소스 유추 엔진으로, AI 기능을 SQL Server 환경에 통합하는 데 적합합니다.

중요합니다

이 기능을 사용하려면 SQL Server Machine Learning Services가 설치되어 있어야 합니다.

1단계: SQL Server 2025에서 개발자 미리 보기 기능 사용

다음 SQL 명령을 실행하여 이 예제에 사용하려는 데이터베이스에서 SQL Server 2025 미리 보기 기능을 사용하도록 설정합니다.

ALTER DATABASE SCOPED CONFIGURATION  
SET PREVIEW_FEATURES = ON;

2단계: SQL Server 2025에서 로컬 AI 런타임 사용

다음 SQL을 실행하여 외부 AI 런타임을 사용하도록 설정합니다.

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

3단계: ONNX 런타임 라이브러리 설정

SQL Server에 ONNX 런타임 라이브러리 파일을 저장할 디렉터리를 만듭니다. 이 예제에서는 C:\onnx_runtime 사용됩니다.

다음 명령을 사용하여 디렉터리를 만들 수 있습니다.

cd C:\
mkdir onnx_runtime

다음으로, 운영 체제에 적합한 ONNX 런타임(버전 ≥ 1.19)을 다운로드 합니다. 다운로드 압축을 풀고 나면 lib 디렉터리에 onnxruntime.dll 있는 디렉터리를 만든 디렉터리에 복사 C:\onnx_runtime 합니다.

4단계: 토큰화 라이브러리 설정

GitHub에서 라이브러리를 tokenizers-cpp 다운로드하고 빌드합니다. dll이 만들어지면 디렉터리에 tokenizer를 C:\onnx_runtime 배치합니다.

비고

만든 dll의 이름이 tokenizers_cpp.dll

5단계: ONNX 모델 다운로드

에서 디렉터리를 model만들어 C:\onnx_runtime\ 시작합니다.

cd C:\onnx_runtime
mkdir model

이 예제에서는 Hugging Face에서 다운로드할 수 있는 모델을 사용합니다all-MiniLM-L6-v2-onnx.

다음 C:\onnx_runtime\model 명령을 사용하여 리포지토리를 디렉터리에 복제합니다.

설치되지 않은 경우 다음 다운로드 링크 또는 winget(winget install Microsoft.Git)을 통해 git을 다운로드할 수 있습니다.

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

6단계: 디렉터리 권한 설정

다음 PowerShell 스크립트를 사용하여 MSSQLLaunchpad 사용자에게 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

7단계: 외부 모델 만들기

다음 SQL을 실행하여 ONNX 모델을 외부 모델 개체로 등록합니다.

여기서 사용되는 'PARAMETERS' 값은 SQL Server 2025 RC 0에 필요한 자리 표시자입니다.

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 는 model.onnx 및 tokenizer.json 파일이 포함된 디렉터리를 가리킵니다.

LOCAL_RUNTIME_PATH 는 onnxruntime.dll 및 tokenizer_cpp.dll 파일이 포함된 디렉터리를 가리킵니다.

8단계: 포함 생성

함수를 ai_generate_embeddings 사용하여 다음 SQL을 실행하여 모델을 테스트합니다.

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

이 명령은 필요한 DLL을 AIRuntimeHost실행하고 입력 텍스트를 처리합니다.

SQL 문의 결과는 포함 배열입니다.

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

XEvent 원격 분석 사용

다음 SQL을 실행하여 문제 해결을 위해 원격 분석을 사용하도록 설정합니다.

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

다음으로, 이 SQL 쿼리를 사용하여 캡처된 원격 분석을 확인합니다.

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

청소

외부 모델 개체를 제거하려면 다음 SQL을 실행합니다.

DROP EXTERNAL MODEL myLocalOnnxModel;

디렉터리 권한을 제거하려면 다음 PowerShell 명령을 실행합니다.

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

마지막으로 디렉터리를 삭제 C:/onnx_runtime 합니다.

다음을 통해 공유

CREATE EXTERNAL MODEL(Transact-SQL)

문법

주장들

external_model_object_name

owner_name

위치

API_FORMAT

모델 유형

모델

자격 증명

매개 변수

LOCAL_RUNTIME_PATH

권한

외부 모델 만들기 및 변경

외부 모델 부여

재시도 횟수

다른 매개 변수를 사용하여 재시도 횟수

비고

HTTPS 및 TLS

허용되는 API 형식 및 모델 형식

EMBEDDINGS에 대한 API_FORMAT

포함 엔드포인트 만들기

EXTERNAL MODEL에 대한 자격 증명 이름 규칙

데이터 정렬 및 자격 증명 이름 규칙

관리되는 식별

스키마바인딩

카탈로그 뷰

원격 엔드포인트가 있는 예제

관리 ID를 사용하여 Azure OpenAI로 EXTERNAL MODEL 만들기

API 키 및 매개 변수를 사용하여 Azure OpenAI로 EXTERNAL MODEL 만들기

Ollama 및 명시적 소유자를 사용하여 EXTERNAL MODEL 만들기

OpenAI를 사용하여 EXTERNAL MODEL 만들기

로컬 ONNX 런타임을 사용하는 예제

1단계: SQL Server 2025에서 개발자 미리 보기 기능 사용

2단계: SQL Server 2025에서 로컬 AI 런타임 사용

3단계: ONNX 런타임 라이브러리 설정

4단계: 토큰화 라이브러리 설정

5단계: ONNX 모델 다운로드

6단계: 디렉터리 권한 설정

7단계: 외부 모델 만들기

8단계: 포함 생성

XEvent 원격 분석 사용

청소

관련 콘텐츠

피드백

추가 리소스