Foundry IQ(Azure AI 검색)에서 인덱스 관리

메모

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

인덱스를 만든 후 Azure 포털을 사용하여 해당 통계 및 정의에 액세스하거나 Foundry IQ 서비스에서 제거할 수 있습니다.

인덱스를 만든 후 Foundry IQ REST API를 사용하여 해당 통계 및 정의에 액세스하거나 Foundry IQ 서비스에서 제거할 수 있습니다.

인덱스를 만든 후 .NET, Java, JavaScript 또는 Python용 Azure SDK를 사용하여 해당 통계 및 정의에 액세스하거나 Foundry IQ 서비스에서 제거할 수 있습니다.

이 문서에서는 콘텐츠에 영향을 주지 않고 인덱스를 관리하는 방법을 설명합니다. 인덱스 정의를 수정하는 방법에 대한 지침은 Foundry IQ에서 인덱스 업데이트 또는 재구축을 참조하세요.

제한점

Foundry IQ 서비스의 가격 책정 계층은 인덱스, 필드 및 문서의 최대 수와 크기를 결정합니다. 자세한 내용은 Foundry IQ의 서비스 제한을 참조하세요.

그렇지 않으면 인덱스 관리에 다음 제한 사항이 적용됩니다.

  • 유지 관리를 위해 인덱스 오프라인으로 전환할 수 없습니다. 인덱스는 항상 검색 작업에 사용할 수 있습니다.

  • Foundry IQ 서비스 내 또는 Foundry IQ 서비스 간에 인덱스를 직접 복사하거나 복제할 수 없습니다. .NET 및 Python용 백업 및 복원 샘플은 정의 및 문서 내보내기를 보여 줍니다. 비밀 정보를 포함하는 정의를 복원하기 전에 인덱스 백업, 복원 또는 복제를 따르세요. 샘플 내보내기가 자격 증명의 백업이 아닙니다.

인덱스 정의에서 시크릿 처리

GET 및 LIST는 자격 증명 백업이 아닌 리소스 정의를 반환합니다. 응답은 다른 리소스를 만드는 데 필요한 비밀을 가리거나 생략할 수 있습니다.

Configuration 읽기 표시 요구 사항 만들기 또는 복사
Azure OpenAI 벡터라이저azureOpenAIParameters.apiKey 저장된 키는 <redacted>로 반환됩니다. 대상 모델 리소스의 키를 제공하거나 지원되는 관리 ID 인증 및 권한 부여를 구성합니다.
사용자 지정 Web API 벡터라이저 customWebApiParameters.httpHeaders 각 헤더 값은 <redacted>로 반환됩니다. 대상 엔드포인트의 헤더 값을 제공합니다.
사용자 지정 Web API 벡터라이저 customWebApiParameters.uri 민감한 code 쿼리 값과 sig 쿼리 값이 가려집니다. 필요한 경우 실제 대상 쿼리 자격 증명을 제공합니다.

<redacted> 및 <unchanged>는 자격 증명이 아닙니다. 동일한 기존 리소스 및 비밀을 포함한 속성에 대해 지원되는 업데이트만 저장된 값을 유지할 수 있습니다. 새 인덱스, 이름이 바뀐 복사본 또는 다른 서비스의 인덱스에는 유지할 원본 비밀이 없습니다. 모든 벡터라이저 또는 API가 동일한 보존 동작을 지원된다고 가정하지 마세요.

Azure OpenAI 벡터라이저의 경우 를 생략하면 apiKey에 따라 관리 ID 인증이 선택됩니다. 생략은 중립적인 ‘나중에 구성’ 상태가 아닙니다. 이 모드를 사용하기 전에 선택한 검색 ID 엔터티와 해당 모델 리소스의 역할 할당을 구성합니다.

모델 키를 사용하여 인덱스 만들기

다음 전체 REST 본문은 text-embedding-3-small 배포를 사용하여 인덱스를 만듭니다. 먼저 리소스 및 배포 값을 사용자의 모델 구성으로 바꾸십시오. 요청을 보내기 전에 ${AZURE_OPENAI_API_KEY}를 클라이언트의 키로 바꾸십시오. 이 표기법은 서비스 쪽 보간이 아니라 클라이언트 쪽 대체입니다. 리터럴 변수를 보내거나 대체된 본문을 소스 제어 또는 로그에 저장하지 마세요.

기존 검색 인증을 사용하여 POST https://<search-service>.search.windows.net/indexes?api-version=2026-10-01를 Content-Type: application/json와 함께 보냅니다:

{
  "name": "model-index",
  "fields": [
    { "name": "id", "type": "Edm.String", "key": true },
    {
      "name": "contentVector", "type": "Collection(Edm.Single)",
      "searchable": true, "dimensions": 1536, "vectorSearchProfile": "model-profile"
    }
  ],
  "vectorSearch": {
    "algorithms": [{ "name": "hnsw", "kind": "hnsw" }],
    "profiles": [{
      "name": "model-profile", "algorithm": "hnsw", "vectorizer": "model-vectorizer"
    }],
    "vectorizers": [{
      "name": "model-vectorizer", "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://contoso.openai.azure.com",
        "deploymentId": "text-embedding-3-small",
        "modelName": "text-embedding-3-small",
        "apiKey": "${AZURE_OPENAI_API_KEY}"
      }
    }]
  }
}

참조: 인덱스 - 만들기

동일한 인덱스 업데이트에서 키 유지

위의 만들기가 실제 키와 함께 성공하면 이 전체 본문은 저장된 키를 유지하면서 동일한 인덱스의 설명을 업데이트합니다. PUT https://<search-service>.search.windows.net/indexes/model-index?api-version=2026-10-01를 동일한 검색 인증 및 JSON 콘텐츠 형식으로 보냅니다.

이 예제에서는 벡터라이저 이름, 종류, 리소스 URI, 배포, 모델 및 인증 모드를 변경하지 않고 유지합니다. Azure OpenAI 벡터라이저는 이름, 종류 및 리소스 URI로 기존 벡터라이저와 일치시킬 수 있는 경우 기존 <redacted>에 대해 <unchanged> 또는 apiKey를 허용합니다. 누락을 키 보존으로 처리하지 마세요. 다른 모델 구성 또는 인증 모드의 경우 의도한 자격 증명을 제공하거나 지원되는 관리 ID를 명시적으로 구성합니다.

{
  "name": "model-index", "description": "Updated description",
  "fields": [
    { "name": "id", "type": "Edm.String", "key": true },
    {
      "name": "contentVector", "type": "Collection(Edm.Single)",
      "searchable": true, "dimensions": 1536, "vectorSearchProfile": "model-profile"
    }
  ],
  "vectorSearch": {
    "algorithms": [{ "name": "hnsw", "kind": "hnsw" }],
    "profiles": [{
      "name": "model-profile", "algorithm": "hnsw", "vectorizer": "model-vectorizer"
    }],
    "vectorizers": [{
      "name": "model-vectorizer", "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://contoso.openai.azure.com",
        "deploymentId": "text-embedding-3-small",
        "modelName": "text-embedding-3-small",
        "apiKey": "<redacted>"
      }
    }]
  }
}

참조: 인덱스 - 만들거나 업데이트합니다.

사용자 지정 Web API 벡터라이저에는 다른 URI 및 헤더 보존 규칙이 있습니다. 이러한 규칙은 다른 벡터라이저의 속성에 대한 보존 지원을 설정하지 않습니다.

자격 증명 유효성 검사 오류 해결

정의를 프로비전하거나 적용하기 전에 요청을 만들고 업데이트하여 구성의 유효성을 검사합니다. 리댁션 자리 표시자를 사용하여 잘못된 리소스를 만들고 나중에 복구할 생각을 하지 마십시오.

요청이 보존 자리 표시자를 기존 비밀과 일치시킬 수 없는 경우 실제 대상 자격 증명을 제공합니다. 인덱스 이름, 벡터라이저 이름 및 종류, 엔드포인트 및 속성을 확인합니다. 사용자 지정 Web API 쿼리 또는 헤더 일치 실패의 경우 속성별 규칙을 따릅니다.

Azure OpenAI 키가 누락되었거나 비어 있는 경우, 관리형 ID를 선택하려고 했는지 확인하세요. 키가 유지되었다고 가정하는 대신 선택한 ID의 권한 부여를 확인합니다. 키와 authIdentity같은 호환되지 않는 인증 설정을 결합하지 마세요. 엔드포인트, 모델 또는 인증을 변경하는 경우 다시 제출하기 전에 대상 자격 증명을 확보하거나 대상 ID를 구성하십시오.

인덱스 백업, 복원 또는 복제

자격 증명과 별도로 정의 및 검색하여 가져올 수 있는 문서를 내보냅니다. GET 또는 LIST에서 반환된 정의는 편집 자리 표시자를 포함하거나 쓰기 전용 속성을 생략할 수 있습니다. 각 리소스 유형의 계약을 검토합니다. 검색만으로 <redacted> 는 충분하지 않습니다.

백업 유틸리티가 GET 응답을 복사하고 인덱스 이름만 변경하고 변경되지 않은 상태로 제출하는 경우 복원 단계를 조정하여 대상 인증을 먼저 제공합니다. 비밀이 포함된 인덱스에는 해당 워크플로를 수정 없이 사용하지 마세요.

  1. 비보안 정의 및 복원해야 하는 문서를 내보냅니다. 비밀을 스키마 백업, 리포지토리 및 로그에서 제외합니다.
  2. 비밀이 포함된 속성에서 가려진 값 및 쓰기 전용 항목의 생략 여부를 검사합니다. 자격 증명 자체를 기록하지 않고 필요한 자격 증명 원본을 기록합니다.
  3. 모델 배포, 외부 연결, 게이트웨이 구성, 엔드포인트 정책, 관리 ID, 역할 할당, 프라이빗 연결 및 고객 관리형 키 액세스와 같은 원본 종속성을 대상에 매핑합니다.
  4. 대상 종속성 및 권한 부여를 다시 만듭니다. 새 Foundry IQ 서비스의 ID는 이전 ID의 역할 또는 네트워크 액세스를 상속하지 않습니다.
  5. 보안 저장소에서 대상 키, OAuth 비밀값 또는 기타 자격 증명을 가져와 각 전체 정의를 제출하기 전에 클라이언트에 주입합니다. 또는 명시적으로 지원되는 관리형 ID 모드를 구성합니다. 원본 보존 자리 표시자를 만들기 요청에 전달하지 마세요.
  6. 종속성 순서로 유효한 대상 리소스를 만듭니다. 성공적인 만들기 또는 GET은 아웃바운드 모델 또는 사용자 지정 API 호출이 성공했음을 증명하지 않습니다.
  7. 제어된 요청을 사용하여 대상 인증, 연결 및 모델 또는 사용자 지정 API 동작의 유효성을 검사합니다. 그런 다음, 애플리케이션을 전환하기 전에 문서를 로드하거나 인덱서를 실행하고 검색 결과를 확인합니다.

지역 이동은 Foundry IQ 서비스를 다른 Azure 지역으로 이동을 참조하세요.

모든 인덱스 보기

모든 인덱스를 보려면:

  1. Azure 포털에서 Foundry IQ 서비스로 이동합니다.

  2. 왼쪽 창에서 검색 관리>인덱스를 선택합니다.

    포털의 인덱스 페이지 스크린샷.

    기본적으로 인덱스는 이름별로 오름차순으로 정렬됩니다. 해당 열 머리글을 선택하여 이름, 문서 수, 벡터 인덱스 할당량 사용량 또는 총 스토리지 크기를 기준으로 정렬할 수 있습니다.

인덱스 - 목록(REST API)을 사용하여 Foundry IQ 서비스의 모든 인덱스를 검색합니다.

### List all indexes
GET https://[service name].search.windows.net/indexes?api-version=[api version]
    Content-Type: application/json
    api-key: [admin key]

2026-10-01 및 2026-11-01-preview REST API에서 목록 작업은 서버 측 페이징을 사용합니다. 더 많은 결과가 있으면 응답에는 continuation URL이 포함됩니다. 응답에 더 이상 포함되지 않을 때까지 각 연속 URL을 따르세요. 전체 패턴 및 예제는 Foundry IQ 목록 결과를 통해 페이지를 참조하세요.

선호하는 Azure SDK를 사용하여 Foundry IQ 서비스의 모든 인덱스를 가져옵니다.

.NET Azure SDK 이 작업에 대해 GetIndexesAsync 제공합니다.

// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);

// List all indexes
await foreach (var index in indexClient.GetIndexesAsync())
{
    Console.WriteLine(index.Name);
}

서버 측 페이징을 사용하는 목록 작업은 추가 결과가 있는 경우 continuation URL을 반환합니다. 지원되는 클라이언트 라이브러리 버전 및 예제는 Page through Foundry IQ 목록 결과를 참조하세요.

인덱스의 통계 보기

인덱스 페이지에서 포털은 다음과 같은 통계를 제공합니다.

  • 인덱스의 문서 수입니다.
  • 인덱스가 사용하는 스토리지 공간입니다.
  • 인덱스가 사용하는 벡터 스토리지 공간입니다.
  • 가격 책정 계층에 따라 달라지는 Foundry IQ 서비스의 각 인덱스에 대한 최대 스토리지 공간입니다. 이 값은 인덱스가 현재 사용할 수 있는 총 스토리지를 나타내지 않습니다.

포털의 인덱스 통계 스크린샷

인덱스 사용 - 통계 가져오기(REST API)를 사용하여 인덱스의 문서 수, 스토리지 사용량 및 벡터 스토리지 사용량을 검색합니다.

### Get index statistics
GET https://[service name].search.windows.net/indexes/[index name]/stats?api-version=[api version]
    Content-Type: application/json
    api-key: [admin key]

원하는 Azure SDK 사용하여 인덱스의 문서 수, 스토리지 사용량 및 벡터 스토리지 사용량을 검색합니다.

.NET Azure SDK 이 작업에 대해 GetIndexStatisticsAsync 제공합니다.

// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);

// Get index statistics
var statsResponse = await indexClient.GetIndexStatisticsAsync("[index name]");
var stats = statsResponse.Value;
Console.WriteLine($"Number of documents: {stats.DocumentCount:N0}");
Console.WriteLine($"Storage consumed by index: {stats.StorageSize:N0} bytes");
Console.WriteLine($"Storage consumed by vectors: {stats.VectorIndexSize:N0} bytes");

인덱스 정의 보기

각 인덱스는 분석기, 정규화기, 토케나이저 및 동의어 맵과 같은 검색 기능을 향상시키는 필드 및 선택적 구성 요소로 정의됩니다. 이 정의는 인덱싱 및 쿼리 중에 인덱스의 구조와 동작을 결정합니다.

인덱스 페이지에서 JSON 편집 을 선택하여 전체 정의를 봅니다.

포털의 JSON 편집 단추 스크린샷

인덱스 사용 - Get(REST API)을 사용하여 인덱스의 JSON 정의를 검색합니다.

### Get index definition
GET https://[service name].search.windows.net/indexes/[index name]?api-version=[api version]
    Content-Type: application/json
    api-key: [admin key]

원하는 Azure SDK 사용하여 인덱스의 JSON 정의를 검색합니다.

.NET Azure SDK 이 작업에 대해 GetIndexAsync 제공합니다.

// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);

// Get index definition
var index = await indexClient.GetIndexAsync("[index name]");
string indexJson = JsonSerializer.Serialize(index.Value, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(indexJson);

인덱스 삭제

경고

인덱스 삭제를 실행 취소할 수 없습니다. 계속하기 전에 Foundry IQ 서비스에서 인덱스와 해당 문서를 영구적으로 제거하려는 것이 맞는지 확인하세요.

인덱스 페이지에서 삭제 를 선택하여 삭제 프로세스를 시작합니다.

포털의 삭제 단추 스크린샷

포털에서 삭제를 확인하라는 메시지가 표시됩니다. 삭제를 선택한 후 알림을 확인하여 삭제에 성공했는지 확인합니다.

포털의 삭제 확인 스크린샷

인덱스 - 삭제(REST API)를 사용하여 인덱스를 영구적으로 삭제합니다.

### Delete an index
DELETE https://[service name].search.windows.net/indexes/[index name]?api-version=[api version]
    Content-Type: application/json
    api-key: [admin key]

인덱스가 성공적으로 삭제되면 HTTP/1.1 204 No Content 응답을 받을 것입니다.

원하는 Azure SDK 사용하여 인덱스 영구적으로 삭제합니다.

.NET Azure SDK 이 작업에 대해 DeleteIndexAsync 제공합니다.

// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);

// Delete the index
await indexClient.DeleteIndexAsync("[index name]");
Console.WriteLine("Index deleted successfully.");