다음을 통해 공유

ai_embeddings 플러그인(미리 보기)

적용 대상: ✅Microsoft Fabric✅Azure Data Explorer

플러그 인을 ai_embeddings 사용하면 언어 모델을 사용하여 텍스트를 포함할 수 있으므로 RAG(검색 보강 세대) 애플리케이션 및 의미 체계 검색과 같은 다양한 AI 관련 시나리오를 사용할 수 있습니다. 플러그 인은 Azure OpenAI Service 포함 모델을 사용하며 관리 ID 또는 사용자의 ID(가장)를 사용하여 액세스할 수 있습니다.

플러그 인을 ai_embeddings 사용하면 언어 모델을 사용하여 텍스트를 포함할 수 있으므로 RAG(검색 보강 세대) 애플리케이션 및 의미 체계 검색과 같은 다양한 AI 관련 시나리오를 사용할 수 있습니다. 플러그 인은 Azure OpenAI 서비스 포함 모델을 사용하며 사용자의 ID(가장)를 사용하여 액세스할 수 있습니다.

필수 조건

  • 관리 ID를 사용하여 Azure OpenAI 서비스에 액세스하는 경우 서비스와의 통신을 허용하도록 관리 ID 정책을 구성합니다.

문법

evaluate ai_embeddings ( 텍스트, connectionString [,옵션 [,IncludeErrorMessages]])

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

이름 유형 필수 설명
문자 메시지 string ✔️ 포함할 텍스트입니다. 값은 열 참조 또는 상수 스칼라일 수 있습니다.
connectionString string ✔️ 언어 모델의 연결 문자열 형식<ModelDeploymentUri>;<AuthenticationMethod>으로, 각각 AI 모델 배포 URI 및 인증 방법으로 바꿉 <ModelDeploymentUri><AuthenticationMethod> 다.
옵션 dynamic 포함 모델 엔드포인트에 대한 호출을 제어하는 옵션입니다. 옵션을 참조하세요.
오류 메시지 포함 bool 출력 테이블의 새 열에서 오류를 출력할지 여부를 나타냅니다. 기본값은 false입니다.

옵션

다음 표에서는 포함 모델 엔드포인트에 대한 요청이 수행되는 방식을 제어하는 옵션에 대해 설명합니다.

이름 유형 설명
RecordsPerRequest int 요청당 처리할 레코드 수를 지정합니다. 기본값은 1입니다.
CharsPerRequest int 요청당 처리할 최대 문자 수를 지정합니다. 기본값: 0 (무제한). Azure OpenAI는 토큰 수를 계산하며 각 토큰은 약 4자로 변환됩니다.
RetriesOnThrottling int 제한이 발생할 때 다시 시도 횟수를 지정합니다. 기본값은 0입니다.
GlobalTimeout timespan 포함 모델의 응답을 기다리는 최대 시간을 지정합니다. 기본값: null
ModelParameters dynamic 모니터링 목적으로 차원 또는 사용자 식별자 포함과 같은 포함 모델과 관련된 매개 변수입니다. 기본값은 null입니다.
ReturnSuccessfulOnly bool 성공적으로 처리된 항목만 반환할지 여부를 나타냅니다. 기본값은 false입니다. IncludeErrorMessages 매개 변수가 설정된 true경우 이 옵션은 항상 .로 false설정됩니다.

설명선 정책 구성

azure_openai 설명선 정책을 사용하면 Azure AI 서비스에 대한 외부 호출이 가능합니다.

AI 모델 엔드포인트 도메인에 권한을 부여하도록 설명선 정책을 구성하려면 다음을 수행합니다.

.alter-merge cluster policy callout
```
[
  {
    "CalloutType": "azure_openai",
    "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*",
    "CanCall": true
  }
]
```

관리 ID 구성

관리 ID를 사용하여 Azure OpenAI 서비스에 액세스하는 경우 시스템 할당 관리 ID 가 Azure OpenAI 서비스에 인증할 수 있도록 관리 ID 정책을 구성해야 합니다.

관리 ID를 구성하려면 다음을 수행합니다.

.alter-merge cluster policy managed_identity
```
[
  {
    "ObjectId": "system",
    "AllowedUsages": "AzureAI"
  }
]
```

반품

다음 새 포함 열을 반환합니다.

  • 임베딩 값을 포함하는 _embeddings 접미사가 있는 열
  • 오류를 반환하도록 구성된 경우 _embedding_error 접미사가 있는 열로, 오류 문자열이 포함되거나 작업이 성공하면 비어 있습니다.

입력 형식에 따라 플러그 인은 다른 결과를 반환합니다.

  • 열 참조: 참조 열 이름 앞에 추가 열이 있는 하나 이상의 레코드를 반환합니다. 예를 들어 입력 열의 이름이 TextData이면 출력 열의 이름은 TextData_embedding 지정되고 오류를 반환하도록 구성된 경우 TextData_embedding_error.
  • 상수 스칼라: 접두사로 지정되지 않은 추가 열이 있는 단일 레코드를 반환합니다. 열 이름은 _embedding 오류를 반환하도록 구성된 경우 _embedding_error.

예시

다음 예제에서는 Azure OpenAI Embedding 모델을 사용하여 텍스트를 Embed this text using AI 포함합니다.

let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embeddings(expression, connectionString)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
evaluate ai_embeddings(expression, connectionString)

다음 예제에서는 Azure OpenAI 포함 모델을 사용하여 여러 텍스트를 포함합니다.

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
  "RecordsPerRequest": 10,
  "CharsPerRequest": 10000,
  "RetriesOnThrottling": 1,
  "GlobalTimeout": 2m
});
datatable(TextData: string)
[
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]
| evaluate ai_embeddings(TextData, connectionString, options , true)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
let options = dynamic({
  "RecordsPerRequest": 10,
  "CharsPerRequest": 10000,
  "RetriesOnThrottling": 1,
  "GlobalTimeout": 2m
});
datatable(TextData: string)
[
  "First text to embed",
  "Second text to embed",
  "Third text to embed"
]
| evaluate ai_embeddings(TextData, connectionString, options , true)

모범 사례

Azure OpenAI 포함 모델에는 많은 제한이 적용되며 이 플러그 인에 대한 잦은 호출은 제한 제한에 빠르게 도달할 수 있습니다.

제한 및 비용을 최소화하면서 플러그 인을 효율적으로 사용 ai_embeddings 하려면 다음 모범 사례를 따르세요.

  • 컨트롤 요청 크기: 요청RecordsPerRequest당 레코드(CharsPerRequest) 및 문자 수를 조정합니다.
  • 쿼리 제한 시간 제어: 쿼리 제한 시간GlobalTimeout낮은 값으로 설정 하여 해당 시점까지의 성공적인 호출에서 진행률이 손실되지 않도록 합니다.
  • 속도 제한을 더 정상적으로 처리: 제한 시 다시 시도 설정(RetriesOnThrottling).

관련 콘텐츠