AI_GENERATE_EMBEDDINGS(Transact-SQL)

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

AI_GENERATE_EMBEDDINGS 는 데이터베이스에 저장된 미리 생성된 AI 모델 정의를 사용하여 포함(벡터 배열)을 만드는 기본 제공 함수입니다.

문법

Transact-SQL 구문 표기 규칙

AI_GENERATE_EMBEDDINGS ( source USE MODEL model_identifier [ PARAMETERS optional_json_request_body_parameters ] )

주장들

원본

모든 문자 형식의 식 입니다(예: nvarchar, varchar, nchar 또는 char).

model_identifier

임베딩 벡터 배열을 생성하는 데 사용되는 타입으로 EMBEDDINGS 정의된 외부 모델의 이름입니다.

자세한 내용은 CREATE EXTERNAL MODEL을 참조하세요.

optional_json_request_body_parameters

유효한 JSON 형식의 추가 매개 변수 목록입니다. 이 매개변수들은 REST 요청 메시지 본체에 덧붙여져 외부 모델의 엔드포인트 위치로 전송됩니다. 이 매개변수들은 외부 모델의 엔드포인트가 지원하고 수용하는 조건에 따라 달라집니다.

반환 형식

AI_GENERATE_EMBEDDINGS 는 행이 JSON으로 반환된 생성된 포함 벡터 배열인 단일 열 테이블을 반환합니다.

반환 형식

반환된 JSON의 형식은 다음과 같습니다.

[
    0.0023929428,
    0.00034713413,
    -0.0023142276,
    -0.025654867,
    -0.011492423,
    0.0010358924,
    -0.014836246,
    0.0035484824,
    0.000045630233,
    -0.027581815,
    0.023816079,
    0.005012586,
    -0.027732948,
    -0.010088143,
    ...
    -0.014571763
]

비고

필수 조건

이용 AI_GENERATE_EMBEDDINGS하려면 다음 전제 조건을 충족해야 합니다:

• 데이터베이스에서 다음 명령어로 활성화(enable this)를 실행 sp_invoke_external_endpoint 하세요:

  EXECUTE sp_configure 'external rest endpoint enabled', 1;
  RECONFIGURE WITH OVERRIDE;
  

• 적절한 부여, 역할, 권한 등을 통해 접근 가능한 해당 유형의 외부 모델을EMBEDDINGS 생성하세요.

선택적 매개 변수

매개 변수 optional_json_request_body_parametersAI_GENERATE_EMBEDDINGS 는 embeddings 요청 메시지의 본문에 엔드포인트 매개 변수를 추가해야 하는 경우에 사용됩니다. 선택적 매개 변수를 추가하면 해당 매개 변수가 모델 정의에 정의된 경우 런타임 시 값이 재정의됩니다.

예를 들어, 외부 모델에 1536 dimensions 으로 설정된 매개변수가 포함되어 있다면, 런타임에 그 매개변수 optional_json_request_body_parameters 를 새로운 값 json_object("dimensions":755)dimensions 으로 전달하여 모델의 매개변수를 덮어쓰게 됩니다.

전달된 optional_json_request_body_parameters 값은 유효한 JSON이어야 합니다.

포함 엔드포인트 만들기

임베딩 엔드포인트 생성에 대한 자세한 내용은 Azure AI Foundry Models, OpenAI, Ollama 내 Azure OpenAI 프로세스를 참고하세요.

확장 이벤트(XEvent)

AI_GENERATE_EMBEDDINGS 에는 문제 해결을 위해 사용할 수 있는 확장 이벤트(ai_generate_embeddings_summary)가 있습니다. 여기에는 상태 코드, 발생한 오류, 사용한 모델 이름 등 REST 요청과 응답에 관한 정보가 포함되어 있습니다. 확장 이벤트에 external_rest_endpoint_summary 는 REST 요청 문제 해결 및 디버깅에 사용할 수 있는 추가 정보가 포함되어 있습니다.

예시

A. SELECT 문을 사용하여 포함 만들기

다음 예시는 select 문으로 결과를 JSON 배열로 반환하는 함수를 AI_GENERATE_EMBEDDINGS 어떻게 사용하는지 보여줍니다.

SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel)
FROM myTable;

B. AI_GENERATE_CHUNKS 사용하여 SELECT 문으로 embeddings 만들기

다음 예시는 AI_GENERATE_CHUNKS 함수를 사용 AI_GENERATE_EMBEDDINGS 해 지정된 청크 크기로 나뉜 텍스트를 select 문으로 전달하는 방법을 보여줍니다. select문은 벡터 배열 결과를 반환합니다.

SELECT id,
       title,
       large_text,
       AI_GENERATE_EMBEDDINGS(c.chunk_text USE MODEL MyAzureOpenAIModel)
FROM myTable
CROSS APPLY AI_GENERATE_CHUNKS (SOURCE = large_text, CHUNK_TYPE = FIXED, CHUNK_SIZE = 10) AS c;

C. 테이블 업데이트를 사용하여 포함 만들기

다음 예제에서는 테이블 업데이트 문과 함께 함수를 사용하여 AI_GENERATE_EMBEDDINGS 벡터 배열 결과를 벡터 데이터 형식 열로 반환하는 방법을 보여줍니다.

UPDATE t
    SET myEmbeddings = AI_GENERATE_EMBEDDINGS(t.text USE MODEL MyAzureOpenAIModel)
FROM myTable AS t;

D. SELECT 문 및 PARAMETERS를 사용하여 포함 만들기

다음 예제에서는 select 문과 함께 함수를 AI_GENERATE_EMBEDDINGS 사용하고 벡터 배열 결과를 반환하는 엔드포인트에 선택적 매개 변수를 전달하는 방법을 보여줍니다.

SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel PARAMETERS TRY_CONVERT (JSON, N'{"dimensions":768}'))
FROM myTable;

E. PARAMETERS 옵션으로 retry_count 임베딩 생성 재시도

embeddings 호출에 임시 문제를 나타내는 HTTP 상태 코드가 발생하면 요청을 자동으로 다시 시도하도록 구성할 수 있습니다.

재시도 횟수를 지정하려면 다음 JSON 파일을 옵션에 PARAMETERS 추가하세요. 이 값은 00()에서 1010() 사이의 양의 정수여야 하며, 이 값은 될 NULL수 없습니다.

비고

쿼리에서 AI_GENERATE_EMBEDDINGS 값이 retry_count 지정되면, 외부 모델의 구성에서 (정의된 경우) 값을 retry_count 덮어씁니다.

SELECT id,
       AI_GENERATE_EMBEDDINGS(large_text USE MODEL MyAzureOpenAIModel PARAMETERS TRY_CONVERT (JSON, N'{"retry_count":10}'))
FROM myTable;

F. 청크, AI_GENERATE_EMBEDDINGS 및 모델 만들기를 사용하는 전체 예제

다음 예시는 데이터를 AI에 맞게 만드는 종단 간 프로세스를 보여줍니다:

1. CREATE external 모델을 사용해 등록하고 임베딩 모델을 접근 가능하게 하세요.

2. AI_GENERATE_CHUNKS로 데이터셋을 더 작은 단위로 나누어 데이터가 모델의 맥락 창 안에 맞도록 하고, 검색 정확도를 높이세요.

3. 임베딩을 생성 AI_GENERATE_EMBEDDINGS하세요.

4. 결과를 벡터 데이터 타입이 있는 테이블에 삽입합니다.

비고

<password> 유효한 암호로 대체합니다.

-- Enable the external REST endpoint invocation on the database server
EXECUTE sp_configure 'external rest endpoint enabled', 1;
RECONFIGURE WITH OVERRIDE;
GO

-- Create a master key for the database
IF NOT EXISTS (SELECT *
               FROM sys.symmetric_keys
               WHERE [name] = '##MS_DatabaseMasterKey##')
    BEGIN
        CREATE MASTER KEY ENCRYPTION BY PASSWORD = N'<password>';
    END
GO

-- 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 an external model to call the Azure OpenAI embeddings REST endpoint
CREATE EXTERNAL MODEL MyAzureOpenAIModel
WITH (
      LOCATION = 'https://my-azure-openai-endpoint.openai.azure.com/openai/deployments/text-embedding-ada-002/embeddings?api-version=2023-05-15',
      API_FORMAT = 'Azure OpenAI',
      MODEL_TYPE = EMBEDDINGS,
      MODEL = 'text-embedding-ada-002',
      CREDENTIAL = [https://my-azure-openai-endpoint.openai.azure.com/]
);

-- Create a table with text to chunk and insert data
CREATE TABLE textchunk
(
    text_id INT IDENTITY (1, 1) PRIMARY KEY,
    text_to_chunk NVARCHAR (MAX)
);
GO

INSERT INTO textchunk (text_to_chunk)
VALUES
('All day long we seemed to dawdle through a country which was full of beauty of every kind. Sometimes we saw little towns or castles on the top of steep hills such as we see in old missals; sometimes we ran by rivers and streams which seemed from the wide stony margin on each side of them to be subject to great floods.'),
('My Friend, Welcome to the Carpathians. I am anxiously expecting you. Sleep well to-night. At three to-morrow the diligence will start for Bukovina; a place on it is kept for you. At the Borgo Pass my carriage will await you and will bring you to me. I trust that your journey from London has been a happy one, and that you will enjoy your stay in my beautiful land. Your friend, DRACULA')
GO

-- Create a new table to hold the chunked text and vector embeddings
CREATE TABLE text_embeddings
(
    embeddings_id INT IDENTITY (1, 1) PRIMARY KEY,
    chunked_text NVARCHAR (MAX),
    vector_embeddings VECTOR(1536)
);

-- Insert the chunked text and vector embeddings into the text_embeddings table using AI_GENERATE_CHUNKS and AI_GENERATE_EMBEDDINGS
INSERT INTO text_embeddings (chunked_text, vector_embeddings)
SELECT c.chunk, AI_GENERATE_EMBEDDINGS(c.chunk USE MODEL MyAzureOpenAIModel)
FROM textchunk t
CROSS APPLY
    AI_GENERATE_CHUNKS(source = t.text_to_chunk, chunk_type = FIXED, chunk_size = 100) c;

-- View the results
SELECT * FROM text_embeddings;

관련 콘텐츠

• CREATE EXTERNAL MODEL(Transact-SQL)
• ALTER EXTERNAL MODEL(Transact-SQL)
• DROP EXTERNAL MODEL(Transact-SQL)
• AI_GENERATE_CHUNKS(Transact-SQL)
• 외부 REST 엔드포인트 호출
• Azure AI Foundry Models 리소스에서 Azure OpenAI 만들기 및 배포