CREATE EXTERNAL MODEL(Transact-SQL)

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

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-ada-002'
    [ , CREDENTIAL = <credential_name> ]
    [ , PARAMETERS = '{"valid":"JSON"}' ]
  );

주장들

external_model_object_name

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

owner_name

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

위치

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

API_FORMAT

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

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

• Azure OpenAI
• OpenAI
• Ollama

모델 유형

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

권한

외부 모델 만들기 및 변경

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>()과 1010(0) 사이의 정수여야 하며 포함되며 음수일 수 없습니다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 모델 유추 엔드포인트 공급자에 대해 다음 링크를 사용합니다.

• Azure OpenAI
• OpenAI
• 올라마 섬

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 규칙보다 더 제한적일 수 있습니다.)

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

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

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

관리되는 식별

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

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

스키마바인딩

데이터베이스 엔진에서 오류를 발생시키는 EXTERNAL MODEL 경우(예: SELECT 문을 사용하여AI_GENERATE_EMBEDDINGS) 만든 SCHEMABINDING 뷰를 삭제하고 참조할 수 없습니다. 뷰 정의 자체를 먼저 수정하거나 삭제하여 참조하는 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 키를 사용합니다. 또한 이 예제에서는 엔드포인트의 Dimensions 매개 변수를 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]
);

관련 콘텐츠

• 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에 대한 역할 기반 액세스 제어