인덱싱된 Azure SQL 기술 자료 만들기

메모

Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.

Important

이 문서에서 (미리 보기)로 표시된 기능 또는 성능은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

Foundry IQ(Azure AI 검색)와 관련된 미리 보기 용어는 미리 보기 기능을 참조하세요.

인덱싱된 Azure SQL 지식 원본은 Azure SQL Database 또는 Azure SQL Managed Instance Azure AI 검색(Foundry IQ)의 에이전트 검색 파이프라인으로 행을 수집합니다. 이 기능은 일반적으로 REST API 2026-10-01에서 사용할 수 있습니다. 지식 원본은 독립적으로 생성되고, 지식 베이스에서 참조되며, 지식 베이스가 런타임에 쿼리될 때 근거 데이터로 사용됩니다.

Azure Blob Storage 및 OneLake와 같은 파일 기반 지식 원본과 달리 각 SQL 행은 하나의 논리 문서로 처리됩니다. 고정 문서 스키마를 사용하는 대신 명시적 열 매핑을 통해 인덱스 스키마를 구동합니다.

인덱싱된 Azure SQL 기술 원본을 만들 때 SQL 데이터 원본, 선택적 열 매핑 및 선택적 모델을 지정하여 다음 Foundry IQ 개체를 자동으로 생성합니다.

  • SQL 테이블 또는 뷰를 나타내는 데이터 원본입니다.
  • 필드가 사용자의 열 매핑을 기반으로 생성된 인덱스입니다.
  • 임베딩을 생성하는 기술 집합입니다. 서비스는 사용자가 지정 embeddingColumns하는 경우에만 기술 세트를 만듭니다.
  • 이전 개체를 사용하여 수집 파이프라인을 구동하는 인덱서입니다.

생성된 인덱서는 Azure SQL 인덱서 준수하며, 필수 구성 요소, 변경 검색 정책 및 제한 사항은 인덱싱된 Azure SQL 기술 원본에도 적용됩니다. 자세한 내용은 Azure SQL 인덱서 설명서 참조하세요.

사용량 지원

Azure 포털 Microsoft Foundry 포털 .NET SDK Python SDK Java SDK JavaScript SDK REST API
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

사전 요구 사항

  • 에이전트 검색을 제공하는 모든 지역의 파운드리 IQ 서비스입니다.

  • 다음을 포함하여 Azure SQL 인덱서 필수 구성 요소 완료:

    • 수집할 테이블 또는 뷰가 있는 Azure SQL Database 또는 Azure SQL Managed Instance.

    • 원본 테이블 또는 뷰의 단일 값으로 구성된 기본 키입니다.

    • 보기의 경우 상위 워터 마크 변경 검색에 적합한 열입니다. rowversion 열을 강력히 권장합니다.

  • 지식 원본을 만들 수 있는 권한입니다. 사용자 계정에 할당된 Search Service 기여자 및 검색 인덱스 데이터 기여자 역할을 사용하여 키 없는 인증을 구성하거나 관리자 API 키를 사용합니다.

  • embeddingColumns를 지정하고 Azure OpenAI 임베딩에 관리 ID를 사용하는 경우, 와 일치하는 Azure OpenAI 또는 상위 Foundry 리소스에서 선택한 ID에 resourceUri 역할을 할당합니다. 역할 할당을 참조하세요.

  • networkAccessMode을 private(으)로 설정하면 다음 요구 사항을 충족하세요.

    • S2, S3, L1 또는 L2 Foundry IQ 서비스를 사용합니다. 구성 및 티어 자격 요건에 대한 공식 공유 프라이빗 링크 지원 매트릭스를 확인합니다.

    • SQL Server에 대한 공유 프라이빗 링크를 만들고 승인합니다. 대상 및 그룹 ID는 지원되는 리소스 유형을 참조하세요. SQL Managed Instance 공유 프라이빗 링크(미리 보기)는 미리 보기로 제공됩니다.

    • 커넥터가 지원하는 경우 SQL 인증 또는 관리 ID를 사용합니다. SQL Managed Instance 공유 프라이빗 링크에는 SQL 인증이 필요합니다. 관리 ID는 해당 연결에 대해 지원되지 않습니다. SQL Database에 관리형 ID를 사용하는 경우 필요한 Azure 및 데이터베이스 역할을 부여합니다. 연결 문자열 및 Database=<database-name>의 리소스 ID를 사용합니다. ingestionParameters.identity은 사용자 할당 ID에 대해서만 설정합니다. 생략하면 인덱서는 Foundry IQ 서비스의 시스템 할당 ID를 사용합니다.

    • 지정 embeddingColumns하는 경우 지원되는 리소스 유형을 사용하여 보호된 각 embedding-model 엔드포인트에 대한 공유 프라이빗 링크를 만들고 승인합니다. 임베딩 열이 없으면 임베딩 기술 세트 또는 모델 연결이 필요하지 않습니다.

  • 최신 Azure.Search.Documents 미리 보기 패키지: dotnet add package Azure.Search.Documents --prerelease

  • 키 없는 인증의 경우 패키지:Azure.Identitydotnet add package Azure.Identity

제한 사항 및 고려 사항

  • 지식 원본은 정확히 하나의 테이블 또는 하나의 뷰에서 수집할 수 있습니다.
  • 원본 테이블 또는 뷰에는 단일 값 기본 키가 있어야 합니다. 복합 키는 지원되지 않습니다.
  • 기본 키는 자동으로 검색되며 재정의할 수 없습니다.
  • contentExtractionMode 에서만 "minimal"지원합니다.
  • 이미지 추출 및 이미지 언어화는 지원되지 않습니다.
  • 실시간 동기화는 지원되지 않습니다. 생성된 인덱서는 일정 기반입니다.
  • 실시간 SQL 검색은 지원되지 않습니다. 기술 원본은 원격이 아니라 인덱싱됩니다.

생성된 인덱서 준비

인덱싱된 Azure SQL 기술 소스는 수집을 구동하는 인덱서가 자동으로 생성됩니다. 기술 자료를 만들기 전에 다음 세부 정보를 검토합니다.

변경 내용 검색

생성된 인덱서는 표준 Azure SQL 인덱서 변경 검색 사용합니다.

인증

생성된 인덱서는 다음 두 가지 인증 옵션을 지원합니다.

  • SQL 인증: 연결 문자열에 사용자 이름 및 암호를 제공합니다.

  • 관리형 ID 인증: SQL 리소스에서 Azure RBAC 및 데이터베이스 수준 역할이 있는 시스템 할당 또는 사용자 할당 관리형 ID를 사용합니다.

연결 문자열 형식, 역할 요구 사항 및 설정 단계는 Azure SQL 인덱서 필수 구성 요소 및 관리 ID를 통해 연결 참조하세요.

기존 지식 원본 확인

기술 자료는 재사용 가능한 최상위 개체입니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.

다음 코드를 실행하여 이름 및 형식별로 기술 자료를 나열합니다.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

참조:SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

참조:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

참조:지식 소스 - 목록

이름으로 단일 기술 원본을 반환하여 JSON 정의를 검토할 수도 있습니다.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

참조:SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

참조:SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}

참조:Knowledge Sources - Get

다음 JSON은 인덱싱된 Azure SQL 기술 소스에 대한 예제 응답입니다.

{
  "name": "indexedsqlks",
  "kind": "indexedSql",
  "description": "Sample indexed Azure SQL knowledge source.",
  "encryptionKey": null,
  "indexedSqlParameters": {
    "connectionString": "<sql-connection-string>",
    "tableOrView": "dbo.tbl_hotels",
    "contentColumns": [
      { "name": "hotelName", "sourceField": "HotelName", "searchFieldType": "Edm.String" },
      { "name": "description", "sourceField": "Description", "searchFieldType": "Edm.String" }
    ],
    "embeddingColumns": [
      { "name": "descriptionVector", "sourceField": "Description" }
    ],
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<aoai-endpoint>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      }
    },
    "createdResources": {
      "datasource": "indexedsqlks-datasource",
      "indexer": "indexedsqlks-indexer",
      "skillset": "indexedsqlks-skillset",
      "index": "indexedsqlks-index"
    }
  }
}

기술 자료 만들기

다음 코드를 실행하여 인덱싱된 Azure SQL 기술 자료를 만듭니다.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
    ContentExtractionMode = "minimal",
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var sqlParams = new IndexedSqlKnowledgeSourceParameters(
    connectionString: sqlConnectionString,
    tableOrView: "dbo.tbl_hotels")
{
    ContentColumns =
    {
        new ContentColumnMapping("hotelName", "HotelName", "Edm.String"),
        new ContentColumnMapping("description", "Description", "Edm.String")
    },
    EmbeddingColumns =
    {
        new EmbeddingColumnMapping("descriptionVector", "Description")
    },
    IngestionParameters = ingestionParams
};

var knowledgeSource = new IndexedSqlKnowledgeSource(
    name: "indexedsqlks",
    indexedSqlParameters: sqlParams)
{
    Description = "Indexed Azure SQL knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

참조:SearchIndexClient, IndexedSqlKnowledgeSource

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizerParameters,
    ContentColumnMapping,
    EmbeddingColumnMapping,
    IndexedSqlKnowledgeSource,
    IndexedSqlKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeSourceAzureOpenAIVectorizer,
    KnowledgeSourceIngestionParameters,
    KnowledgeSourceNetworkAccessMode,
)

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())

embedding_params = AzureOpenAIVectorizerParameters(
    resource_url="<aoai-endpoint>",
    deployment_name="<aoai-embedding-deployment>",
    model_name="<aoai-embedding-model>",
)

ingestion_params = KnowledgeSourceIngestionParameters(
    network_access_mode=KnowledgeSourceNetworkAccessMode.PUBLIC,
    content_extraction_mode="minimal",
    embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
        azure_open_ai_parameters=embedding_params
    ),
)

knowledge_source = IndexedSqlKnowledgeSource(
    name="indexedsqlks",
    description="Indexed Azure SQL knowledge source.",
    indexed_sql_parameters=IndexedSqlKnowledgeSourceParameters(
        connection_string="Server=tcp:{server}.database.windows.net,1433;Database={db};...;",
        table_or_view="dbo.tbl_hotels",
        content_columns=[
            ContentColumnMapping(
                name="hotelName",
                source_field="HotelName",
                search_field_type="Edm.String",
            ),
            ContentColumnMapping(
                name="description",
                source_field="Description",
                search_field_type="Edm.String",
            ),
        ],
        embedding_columns=[
            EmbeddingColumnMapping(
                name="descriptionVector",
                source_field="Description",
            )
        ],
        ingestion_parameters=ingestion_params,
    ),
)

index_client.create_or_update_knowledge_source(knowledge_source=knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

참조:SearchIndexClient

### Create an indexed Azure SQL knowledge source
PUT {{search-endpoint}}/knowledgesources/indexedsqlks?api-version=2026-10-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation

{
  "name": "indexedsqlks",
  "kind": "indexedSql",
  "description": "Indexed Azure SQL knowledge source.",
  "indexedSqlParameters": {
    "connectionString": "Server=tcp:{server}.database.windows.net,1433;Database={db};...;",
    "tableOrView": "dbo.tbl_hotels",
    "contentColumns": [
      { "name": "hotelName", "sourceField": "HotelName", "searchFieldType": "Edm.String" },
      { "name": "description", "sourceField": "Description", "searchFieldType": "Edm.String" }
    ],
    "embeddingColumns": [
      { "name": "descriptionVector", "sourceField": "Description" }
    ],
    "ingestionParameters": {
      "networkAccessMode": "public",
      "contentExtractionMode": "minimal",
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      }
    }
  }
}

참조:Knowledge Sources - 만들기 또는 업데이트

수집할 SQL 테이블 또는 뷰를 식별하고 생성된 인덱스의 필드가 되는 열 매핑을 정의하는 데 사용합니다 indexedSqlParameters . 뷰의 경우 변경 감지에 사용되는 하이 워터 마크 열을 지정합니다.

열 매핑

생성된 Foundry IQ 인덱스의 검색 가능한 필드에 SQL 텍스트 열을 매핑하는 데 사용합니다 contentColumns . 각 콘텐츠 열 매핑은 대상 인덱스 필드, 원본 SQL 열 및 Foundry IQ 필드 형식의 이름을 지정합니다. contentColumns의 경우 Edm.String을 사용합니다.

임베딩 매핑

SQL 텍스트 열을 생성된 벡터 필드에 매핑하는 데 사용합니다 embeddingColumns . 포함 열을 사용할 때 포함 모델을 ingestionParameters 지정합니다.

인덱싱된 Azure SQL 기술 자료 원본의 경우 SQL 수집은 행 기반이며 이진 문서에서 콘텐츠를 추출하지 않으므로 contentExtractionMode은(는) "minimal"이어야 합니다. 이미지 추출 및 이미지 언어화는 지원되지 않으므로 chatCompletionModel, assetStoreaiServices및 이미지 관련 설정은 영향을 주지 않습니다.

기본값 설정 및 유효성 검사 규칙

인덱싱된 Azure SQL 기술 자료를 만들 때 적용되는 기본값은 다음과 같습니다.

  • contentColumns를 생략하면 서비스는 Edm.String가 name와 같은 1:1 매핑을 사용하여, 텍스트로 안전하게 표현할 수 있는 SQL 열을 생성된 인덱스의 sourceField 필드에 자동으로 매핑합니다.

  • 생략 embeddingColumns하면 서비스는 벡터 필드를 만들지 않고 포함 기술을 구성하지 않습니다.

  • embeddingColumns는 contentColumns와는 독립적입니다. 벡터가 검색 가능한 텍스트에 해당하도록 하려면 두 배열에 동일한 SQL 열을 포함합니다.

  • 원본 테이블 또는 뷰의 기본 키는 자동으로 검색됩니다. 명시적 재정의는 지원되지 않으며 원본에는 단일 값 기본 키가 있어야 합니다.

프라이빗 네트워크로 수집 제한

안정적인 2026-10-01 API에서 networkAccessMode는 인덱싱된 Azure SQL 기술 원본에 대해 생성된 인덱서가 실행되는 네트워크 환경을 제어합니다. 이 설정은 수집에만 영향을 미치며 기술 자료 검색 요청 또는 응답을 변경하지 않습니다. 적합한 구성 및 독립적인 미리 보기 종속성에 대한 공유 프라이빗 링크 지원 매트릭스 를 확인합니다.

networkAccessMode의 기본값은 public이며, 기존 공용 네트워크 동작을 유지합니다. 이 경우 networkAccessModeprivate생성된 인덱서는 프라이빗 실행 환경에서 실행됩니다. 승인된 공유 프라이빗 링크를 사용하여 Azure SQL Database 또는 SQL Managed Instance 원본 연결에 액세스하고 Azure OpenAI 모델 및 Microsoft Foundry 리소스와 같은 지원되는 Azure 종속성에 액세스합니다.

프라이빗 네트워크 액세스를 구성하고 확인하려면 다음을 수행합니다.

  1. 프라이빗 네트워크 필수 구성 요소를 완료합니다.

  2. 지식 소스 생성 요청에서 private을(를) networkAccessMode(으)로 설정합니다. 안정적인 2026-10-01 API를 포함하여 만드는 동안에만 이 속성을 설정할 수 있습니다. 저장 모드를 나중에 변경하려면 지식 원본을 삭제하고 다시 만듭니다. 적격 Blob, ADLS Gen2 및 Azure SQL 원본은 대신 임시로 생성된 인덱서 네트워킹 재정의를 사용할 수 있습니다. 이 예외는 인덱싱된 SharePoint 또는 다른 원본 종류에는 적용되지 않습니다.

    서비스 계층 또는 런타임이 프라이빗 실행을 지원하지 않거나 필요한 공유 프라이빗 링크가 없는 경우 생성이 실패할 수 있습니다. 서버리스 및 S3 HD는 프라이빗 실행을 지원하지 않습니다. 네트워크 보안 경계 구성은 프라이빗 실행이 아니라 지원되는 퍼블릭 엔드포인트 액세스를 제어합니다.

  3. 생성된 인덱서가 parameters.configuration.executionEnvironment .인지 private확인합니다.

  4. 필요한 각 공유 프라이빗 링크가 승인되고 프로비전되었으며 올바른 종속성을 대상으로 하는지 확인합니다. 만들기에 성공해도 링크 승인 또는 대상 지정은 확인되지 않습니다. 포털 검사에서 구독 간 리소스를 확인할 수 없는 경우 대상 리소스 및 Foundry IQ 서비스에 대한 승인 및 준비 상태를 수동으로 확인합니다.

  5. lastSynchronizationState.endTime에 값이 있을 때까지 지식 소스 상태를 폴링합니다. itemsUpdatesFailed이(가) 0인지 확인한 다음, 커넥터별 원본 콘텐츠를 확인합니다. 종속성에 연결할 수 없는 경우 동기화가 실패합니다.

수집 상태 확인

다음 코드를 실행하여 인덱서 파이프라인을 생성하고 검색 인덱스를 채우는 지식 원본에 대한 기술 자료 종류 및 자세한 인덱싱 오류를 포함하여 수집 진행률 및 상태를 모니터링합니다.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get knowledge source ingestion status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;

// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

참조:SearchIndexClient

# Check knowledge source ingestion status
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint="search_url", credential=AzureKeyCredential("api_key"))

status = index_client.get_knowledge_source_status("knowledge_source_name")
print(json.dumps(status.as_dict(), indent=2))

참조:SearchIndexClient

### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
Authorization: Bearer {{token}}
Content-Type: application/json 

참조:지식 원본 - 상태 조회

수집 매개 변수를 포함하고 콘텐츠를 적극적으로 수집하는 요청에 대한 응답은 다음 예제와 같습니다.

{
  "kind": "azureBlob",
  "synchronizationStatus": "active",
  "synchronizationInterval": "1d",
  "currentSynchronizationState": {
    "startTime": "2026-04-10T19:30:00Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": [
      {
        "key": "Item id 1",
        "docURL": "https://contoso.blob.core.windows.net/contracts/2024/Q4/doc-00023.csv",
        "statusCode": 400,
        "componentName": "DocumentExtraction.AzureBlob.MyDataSource",
        "errorMessage": "Could not read the value of column 'foo' at index '0'.",
        "details": "The file could not be parsed.",
        "documentationLink": "https://go.microsoft.com/fwlink/?linkid=2049388"
      }
    ]
  },
  "lastSynchronizationState": {
    "status": "partialSuccess",
    "startTime": "2026-04-09T19:30:00Z",
    "endTime": "2026-04-09T19:40:01Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": null
  },
  "statistics": {
    "totalSynchronizations": 25,
    "averageSynchronizationDuration": "00:15:20",
    "averageItemsProcessedPerSynchronization": 500
  }
}

메모

kind 문서 수준 오류 세부 정보가 포함된 속성 및 currentSynchronizationState.errors[] 배열은 2026-04-01 API 버전부터 사용할 수 있습니다. 이전 API 버전의 경우 이러한 필드는 반환되지 않습니다. 이 lastSynchronizationState.status 필드는 2026-04-01년에도 새로 추가되었습니다.

생성된 개체 검토

이 지식 원본을 만들면 Foundry IQ (Azure AI 검색)는 데이터 원본, 인덱서, 인덱스를 자동으로 생성하며, 수집 파이프라인에 필요한 경우 기술 집합도 생성합니다. 만들기 응답은 아래 createdResources의 각 개체를 나열합니다.

이러한 개체는 고정 템플릿에 따라 생성되며 해당 이름은 기술 자료의 이름을 기반으로 합니다. 개체 이름은 변경할 수 없습니다. 변경으로 인해 인덱서 파이프라인을 중단하는 오류 또는 비호환성이 발생할 수 있으므로 이러한 개체를 직접 편집하지 마십시오.

적격한 Blob, ADLS Gen2 및 Azure SQL 원본에만 임시 네트워킹 재정의를 통해 생성된 인덱서의 실행 환경을 변경할 수 있습니다. 이 예외는 인덱싱된 SharePoint 또는 OneLake에는 적용되지 않으며 다른 생성된 개체 변경은 허용하지 않습니다. 나중에 기술 자료 업데이트 또는 다시 생성은 재정의를 덮어쓸 수 있습니다.

Azure 포털을 사용하여 개체 만들기의 유효성을 검사할 수 있습니다. 워크플로는 다음과 같습니다.

  1. 인덱서에서 성공 또는 실패 메시지를 확인합니다. 연결 또는 할당량 오류가 여기에 표시됩니다.

  2. 데이터 원본을 확인하여 데이터 저장소에 대한 연결을 확인합니다. 연결은 지식 원본을 구성한 방식에 따라 연결 문자열 또는 관리되는 ID를 사용합니다.

  3. 기술 세트가 생성되면 해당 보강 및 벡터화 설정을 확인합니다. SQL 지식 원본은 embeddingColumns를 지정할 때만 기술 세트를 생성합니다.

  4. 검색 가능하고 필터링 가능한 필드와 유사성 검색을 위해 벡터를 저장하는 필드를 포함하여 검색을 위해 콘텐츠가 인덱싱되고 노출되는 방식을 확인하려면 인덱스를 확인합니다. 검색 탐색기를 사용하여 생성된 인덱스에 대해 쿼리를 실행합니다.

기술 자료에 할당

기술 자료에 만족하는 경우 기술 자료에 추가합니다.

지식 베이스 질의

기술 자료가 구성되면 검색 작업 또는 MCP 엔드포인트를 호출 하여 기술 자료를 쿼리합니다.

지식 원본 삭제

기술 자료를 삭제하려면 먼저 이를 참조하는 기술 자료를 삭제하거나 기술 자료 정의를 업데이트하여 참조를 제거해야 합니다. 인덱스 및 인덱서 파이프라인을 생성하는 기술 원본의 경우 생성된 모든 개체 도 삭제됩니다. 그러나 기존 인덱스로 기술 원본을 만든 경우 인덱스가 삭제되지 않습니다.

사용 중인 기술 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 기술 자료 목록이 반환됩니다.

기술 자료를 삭제하려면 다음을 수행합니다.

  1. Foundry IQ 서비스의 모든 기술 자료 베이스 목록을 가져옵니다.

    using Azure.Search.Documents.Indexes;
    
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
    
    Console.WriteLine("Knowledge Bases:");
    
    await foreach (var kb in knowledgeBases)
    {
        Console.WriteLine($"  - {kb.Name}");
    }
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

    using Azure.Search.Documents.Indexes;
    using System.Text.Json;
    
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    
    // Specify the knowledge base name to retrieve
    string kbNameToGet = "earth-knowledge-base";
    
    // Get a specific knowledge base definition
    var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
    var kb = knowledgeBaseResponse.Value;
    
    // Serialize to JSON for display
    string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
    Console.WriteLine(json);
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. 기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

    using Azure.Search.Documents.Indexes;
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    
    await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
    System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");
    

    참조:SearchIndexClient

  4. 기술 자료를 삭제합니다.

    await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
    System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
    

    참조:SearchIndexClient

  1. Foundry IQ 서비스의 모든 기술 자료 목록을 가져옵니다.

    # Get knowledge bases
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    
    print("Knowledge Bases:")
    for kb in index_client.list_knowledge_bases():
        print(f"  - {kb.name}")
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

    # Get a knowledge base definition
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    kb = index_client.get_knowledge_base("knowledge_base_name")
    print(kb)
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. 기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

    # Delete a knowledge base
    from azure.core.credentials import AzureKeyCredential 
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    index_client.delete_knowledge_base("knowledge_base_name")
    print(f"Knowledge base deleted successfully.")
    

    참조:SearchIndexClient

  4. 기술 자료를 삭제합니다.

    # Delete a knowledge source
    from azure.core.credentials import AzureKeyCredential 
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    index_client.delete_knowledge_source("knowledge_source_name")
    print(f"Knowledge source deleted successfully.")
    

    참조:SearchIndexClient

  1. Foundry IQ 서비스의 모든 기술 자료 목록을 가져옵니다.

    ### Get knowledge bases
    GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
    Authorization: Bearer {{token}}
    

    참조:지식 베이스 - 목록

    예제 응답은 다음과 같을 수 있습니다.

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

    ### Get a knowledge base definition
    GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    참조:지식 베이스 - 가져오기

    예제 응답은 다음과 같을 수 있습니다.

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. 기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

    ### Delete a knowledge base
    DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    참조:기술 자료실 - 삭제

  4. 기술 자료를 삭제합니다.

    ### Delete a knowledge source
    DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    참조:지식 소스 - 삭제