CREATE EXTERNAL MODEL(Transact-SQL)

적용 대상: SQL Server 2025 (17.x) Azure SQL DatabaseSQL 데이터베이스 in Microsoft Fabric

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

문법

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

주장들

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입니다.

자격 증명

AI 모델 추론 엔드포인트에 사용되는 객체를 지정합니다 DATABASE SCOPED CREDENTIAL . 허용되는 자격 증명 유형과 명명 규칙에 대한 자세한 내용은 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> } }

예를 들어, 를 retry_count 3으로 설정하려면 다음 JSON 문자열을 사용하세요:

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

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

JSON 문자열이 유효하다면 재시도 횟수를 다른 매개변수와 결합할 수 있습니다.

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

비고

HTTPS 및 TLS

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

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

다음 섹션에서는 각 MODEL_TYPE.

EMBEDDINGS에 대한 API_FORMAT

이 표는 모델 유형에 대한 EMBEDDINGS API 형식과 URL 엔드포인트 구조를 개괄합니다. 특정 페이로드 구조를 보려면 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 모델 유추 엔드포인트 공급자에 대해 다음 링크를 사용합니다.

• Azure AI 파운드리 모델의 Azure OpenAI
• OpenAI
• 올라마 섬

외부 모델의 자격 증명 이름 규칙

외부 모델이 사용하는 생성 DATABASE SCOPED CREDENTIAL 물은 다음 규칙을 따라야 합니다:

• 유효한 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 규칙보다 더 제한적일 수 있는데, 예를 들어 데이터베이스가 대소문자 구별 콜레이션을 사용하도록 설정되어 있을 경우입니다.)

1. RFC를 사용하여 URL 및 자격 증명이 일치하는지 확인합니다. 즉, 다음을 의미합니다.

   • 대/소문자를 구분하지 않는 데이터 정렬을 사용하여 구성표 및 호스트 확인(Latin1_General_100_CI_AS_KS_WS_SC)
   • URL의 다른 모든 세그먼트가 대/소문자를 구분하는 데이터 정렬에서 비교되는지 확인합니다(Latin1_General_100_BIN2).

2. URL 및 자격 증명이 데이터베이스 데이터 정렬 규칙을 사용하여 일치하는지 확인합니다(URL 인코딩을 수행하지 않고).

관리형 아이덴티티

SQL Server 2025(17.x)에서 Arc/VM 호스트의 관리 신원을 데이터베이스 수준의 자격 증명으로 사용하려면 ALTER SETTINGS 서버 수준 권한이 부여된 사용자와 함께 옵션을 sp_configure 활성화해야 합니다.

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

스키마바인딩

외부 모델을 참조하는 뷰(예: SELECT 를 사용하는 AI_GENERATE_EMBEDDINGS문장)로 SCHEMABINDING 생성된 뷰는 버릴 수 없으며, 데이터베이스 엔진이 오류를 발생시킵니다. 외부 모델을 참조하는 의존성을 제거하려면 먼저 뷰 정의를 수정하거나 삭제해야 합니다.

카탈로그 보기

sys.external_models 카탈로그 뷰를 쿼리하여 외부 모델 메타데이터를 볼 수 있습니다. 메타데이터를 보려면 모델에 접근할 수 있어야 합니다.

SELECT *
FROM sys.external_models;

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

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

이 예시는 Azure OpenAI를 사용해 해당 EMBEDDINGS 유형의 외부 모델을 생성하고, 인증을 위해 관리 신원(Managed Identity) 을 사용합니다.

SQL Server 2025(17.x) 이후 버전에서는 SQL Server를 Azure Arc에 연결 하고 기본 관리 신원을 활성화해야 합니다.

중요합니다

Azure OpenAI 및 SQL Server 2025 (17.x)에서 관리 신원을 사용할 경우, Azure Arc가 활성화한 SQL Server의 시스템 할당 관리 신원에 인지 서비스 OpenAI 기여자 역할이 부여되어야 합니다. 자세한 내용은 Azure AI Foundry 모델의 '역할 기반 접근 제어'를 참조하세요.

관리 신원을 사용하여 Azure OpenAI에 접근 자격 증명을 생성하세요:

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

외부 모델 만들기:

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 키와 매개변수를 사용해 Azure OpenAI로 외부 모델을 만듭니다

이 예시는 Azure OpenAI를 사용해 해당 EMBEDDINGS 유형의 외부 모델을 생성하고 인증을 위해 API 키를 사용합니다. 또한 이 예제에서는 엔드포인트의 차원 매개 변수를 725로 설정하는 데도 사용합니다 PARAMETERS .

키를 사용하여 Azure OpenAI에 접근 자격 증명을 생성하세요:

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

외부 모델 만들기:

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 및 명시적 소유자를 사용하여 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 만들기

이 예시는 OpenAI API_FORMAT 와 HTTP 헤더 기반 자격 증명을 이용해 인증에 대해 해당 EMBEDDINGS 유형의 외부 모델을 만듭니다.

-- 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 런타임이 로컬에서 실행되는 예시

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

이 예시는 SQL Server 2025(17.x)를 ONNX 런타임과 함께 설정하여 로컬 AI 기반 텍스트 임베딩 생성을 가능하게 하는 과정을 안내합니다. Windows에서만 적용됩니다.

중요합니다

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

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

이 예시에 사용하려는 데이터베이스에서 SQL Server 2025 (17.x) 미리보기 기능을 활성화하려면 다음 Transact-SQL(T-SQL) 명령을 실행하세요:

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

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

다음 T-SQL 쿼리를 실행하여 외부 AI 런타임을 활성화하세요:

EXECUTE 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

이 예제에서는 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단계: 외부 모델 만들기

다음 쿼리를 실행하여 ONNX 모델을 외부 모델 객체로 등록하세요:

여기서 사용된 'PARAMETERS' 값은 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 와 파일이 포함된 model.onnxtokenizer.json 디렉터리를 가리켜야 합니다.
• LOCAL_RUNTIME_PATH 디렉터리 내 onnxruntime.dll 와 tokenizer_cpp.dll 파일을 가리켜야 합니다.

8단계: 포함 생성

다음 쿼리를 실행하여 모델을 테스트할 수 있는 함수를 ai_generate_embeddings 사용하세요:

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

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

이전 쿼리의 결과는 임베딩 배열입니다:

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

XEvent 시스템 로깅 활성화

문제 해결을 위해 시스템 로깅을 활성화하려면 다음 쿼리를 실행하세요.

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

다음으로, 캡처된 시스템 로그를 참고하세요:

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

청소

외부 모델 객체를 제거하려면 다음 T-SQL 문장을 실행하세요:

DROP EXTERNAL MODEL myLocalOnnxModel;

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

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

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

관련 콘텐츠

• ALTER EXTERNAL MODEL(Transact-SQL)
• DROP EXTERNAL MODEL(Transact-SQL)
• AI_GENERATE_EMBEDDINGS(Transact-SQL)
• AI_GENERATE_CHUNKS(Transact-SQL)
• sys.external_models
• Azure AI Foundry Models 리소스에서 Azure OpenAI 만들기 및 배포
• 서버 구성 옵션
• Azure AI Foundry 모델에서 Azure OpenAI에 대한 역할 기반 액세스 제어