CREATE EXTERNAL MODEL(Transact-SQL)

: SQL Server 2025(17.x) Azure SQL Database<>< Azure SQL Managed InstanceSQL 데이터베이스(Microsoft Fabric

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

비고

CREATE EXTERNAL MODEL Always-up-to-dateupdate 정책 Azure SQL Managed Instance 사용할 수 있습니다.

문법

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 모델 유추 엔드포인트 공급자에 대해 다음 링크를 사용합니다.

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

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

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

관리형 아이덴티티

Arc/VM 호스트의 관리 ID를 2025년 SQL Server 데이터베이스 수준 자격 증명으로 사용하려면(17.) x) ALTER SETTINGS 서버 수준 권한을 granted 사용자와 함께 sp_configure 사용하여 옵션을 사용하도록 설정해야 합니다.

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

스키마바인딩

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

카탈로그 보기

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

SELECT *
FROM sys.external_models;

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

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

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

SQL Server 2025(17.x) 이상 버전에서는 SQL Server 을 Azure Arc에 연결하고 기본 관리 ID를 사용하도록 설정해야 합니다.

중요합니다

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

관리 ID를 사용하여 OpenAI를 Azure 액세스 자격 증명을 만듭니다.

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 .

키를 사용하여 OpenAI를 Azure 액세스 자격 증명을 만듭니다.

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

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

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

중요합니다

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

보안 고려 사항

AI 런타임 호스트 기능을 사용하여 SQL Server 사용자 고유의 LLM 및 ONNX 라이브러리를 구성하고 사용할 수 있습니다. Microsoft 타사 모델 및 라이브러리의 유효성을 검사하거나 모니터링하지 않으므로 적절한 모델 및 라이브러리를 선택하고, 콘텐츠를 필터링하고, 런타임을 보호하며, 해당 정책 및 규정 준수를 보장할 책임이 있습니다.

주의

악의적이거나 손상된 ONNX 모델은 데이터를 유출하거나 권한 없는 코드를 실행할 수 있습니다. 신뢰할 수 있는 확인된 원본의 모델만 사용합니다.

이러한 위험을 완화하려면 다음 보안 모범 사례를 고려하세요.

강력한 액세스 제어 구현: 권한 있는 사용자만 중요한 데이터 및 ONNX 런타임 모델에 액세스할 수 있는지 확인합니다. SQL Server 로드하기 전에 모든 모델의 유효성을 검사합니다. 데이터베이스 역할 및 권한뿐만 아니라 최소 권한 원칙을 사용합니다.
액세스 모니터링 및 감사: 데이터베이스 AI_GENERATE_EMBEDDINGS 및 함수 호출에 대한 액세스를 정기적으로 모니터링하고 감사하여 의심스러운 활동을 검색합니다.
정기적인 보안 평가 수행: 취약성 검사 및 보안 검토를 수행하여 잠재적 위험을 식별하고 완화합니다.

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

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

ALTER DATABASE SCOPED CONFIGURATION
SET PREVIEW_FEATURES = ON;

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

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

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

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

ONNX 런타임 라이브러리 파일을 저장할 SQL Server 인스턴스에 디렉터리를 만듭니다. 이 예제에서는 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 합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-08