Knowledge Bases - Create

새 기술 자료를 만듭니다.

POST {endpoint}/knowledgebases?api-version=2026-11-01-preview

URI 매개 변수

속성 In(다음 안에) 필수 형식 Description
endpoint
path True

string (uri)

검색 서비스의 엔드포인트 URL입니다.

api-version
query True

string

minLength: 1

이 작업에 사용할 API 버전입니다.

요청 헤더

속성 필수 형식 Description
x-ms-client-request-id

string (uuid)

요청에 대한 불투명하고 전역적으로 고유한 클라이언트 생성 문자열 식별자입니다.

Accept

Accept

Accept 헤더입니다.

요청 본문

속성 필수 형식 Description
knowledgeSources True

KnowledgeSourceReference[]

이 지식 베이스에서 참조하는 지식 출처.

name True

string

기술 자료의 이름.

@odata.etag

string

기술 자료의 ETag입니다.

answerInstructions

string

답변을 생성할 때 지식 기반에서 고려하는 지침들.

corsOptions

CorsOptions

지식 베이스의 교차 원산 자원 공유(CORS) 제어 옵션.

description

string

기술 자료에 대한 설명입니다.

encryptionKey

SearchResourceEncryptionKey

Azure Key Vault에서 만드는 암호화 키에 대한 설명입니다.

models KnowledgeBaseModel[]:

AI 모델에 연결하는 방법에 대한 구성 옵션이 포함되어 있습니다.

outputMode

KnowledgeRetrievalOutputMode

지식 기반의 출력 모드입니다.

retrievalInstructions

string

쿼리 계획을 개발할 때 지식 베이스에서 고려하는 지침들.

retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

검색 추론 노력 구성.

retrieveDefaults

KnowledgeBaseRetrieveDefaults

이 지식 기반의 지속적인 요청 전체 조회 기본값입니다. 이 값들은 해당 필드가 생략된 요청을 가져오는 데 적용됩니다; 존재할 경우 요청 시간 값이 우선권을 가집니다.

tags

object

지식 베이스를 분류하고 사용 및 비용을 부여하기 위한 사용자 정의 키-값 쌍.

tools

KnowledgeBaseTool[]

명명된 검색 도구들로, 각각 이 지식 기반의 일부 출처로 제한됩니다. 구성이 이루어지면, MCP는 전체 지식 기반에서 데이터를 가져오는 내장 knowledge_base_retrieve 도구와 더불어 이러한 도구들을 광고합니다. 이 API 버전에서 도구를 누락하거나 빈 배열을 제공하면 기존 도구가 삭제됩니다.

응답

속성 형식 Description
201 Created

KnowledgeBase

요청이 성공했고 결과적으로 새 리소스가 생성되었습니다.

Other Status Codes

ErrorResponse

예기치 않은 오류 응답입니다.

보안

api-key

형식: apiKey
In(다음 안에): header

OAuth2Auth

형식: oauth2
Flow: implicit
권한 부여 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

범위

속성 Description
https://search.azure.com/.default

예제

SearchServiceCreateKnowledgeBase
SearchServiceCreateKnowledgeBaseMicrosoftRetriever1
SearchServiceCreateKnowledgeBaseOpenAICompatible
SearchServiceCreateKnowledgeBaseOpenAICompatibleSystemAssignedIdentity

SearchServiceCreateKnowledgeBase

샘플 요청

POST https://typespecpreviewexampleservice.search.windows.net/knowledgebases?api-version=2026-11-01-preview



{
  "name": "base-preview-test",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4.1-nano"
      }
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "extractiveData",
  "@odata.etag": "0x1234568AE7E58A1",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "description": "Description of the knowledge base.",
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  }
}

샘플 응답

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "base-preview-test",
  "description": "Description of the knowledge base.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "outputMode": "extractiveData",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4.1-nano"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "isServiceLevelKey": false,
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  },
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ]
}

SearchServiceCreateKnowledgeBaseMicrosoftRetriever1

샘플 요청

POST https://typespecpreviewexampleservice.search.windows.net/knowledgebases?api-version=2026-11-01-preview



{
  "name": "travel-knowledgebase",
  "knowledgeSources": [
    {
      "name": "hotels"
    }
  ],
  "models": [
    {
      "kind": "microsoftRetriever1"
    }
  ],
  "outputMode": "extractiveData",
  "description": "Find hotels using Microsoft Retriever 1."
}

샘플 응답

{
  "name": "travel-knowledgebase",
  "knowledgeSources": [
    {
      "name": "hotels"
    }
  ],
  "models": [
    {
      "kind": "microsoftRetriever1"
    }
  ],
  "outputMode": "extractiveData",
  "description": "Find hotels using Microsoft Retriever 1."
}

SearchServiceCreateKnowledgeBaseOpenAICompatible

샘플 요청

POST https://typespecpreviewexampleservice.search.windows.net/knowledgebases?api-version=2026-11-01-preview



{
  "name": "compatible-model-preview-test",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ],
  "models": [
    {
      "kind": "openAICompatible",
      "openAICompatibleParameters": {
        "uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
        "modelName": "gpt-4.1-mini",
        "headers": {
          "api-key": "EXAMPLE-NOT-A-REAL-SECRET"
        }
      }
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "extractiveData",
  "@odata.etag": "0x1234568AE7E58A1",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "description": "Description of the knowledge base.",
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  }
}

샘플 응답

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "compatible-model-preview-test",
  "description": "Description of the knowledge base.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "outputMode": "extractiveData",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "kind": "openAICompatible",
      "openAICompatibleParameters": {
        "uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
        "modelName": "gpt-4.1-mini"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "isServiceLevelKey": false,
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  },
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ]
}

SearchServiceCreateKnowledgeBaseOpenAICompatibleSystemAssignedIdentity

샘플 요청

POST https://typespecpreviewexampleservice.search.windows.net/knowledgebases?api-version=2026-11-01-preview



{
  "name": "compatible-model-preview-test",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ],
  "models": [
    {
      "kind": "openAICompatible",
      "openAICompatibleParameters": {
        "uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
        "modelName": "gpt-4.1-mini",
        "managedIdentityAudience": "11111111-2222-3333-4444-555555555555"
      }
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "extractiveData",
  "@odata.etag": "0x1234568AE7E58A1",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "description": "Description of the knowledge base.",
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  }
}

샘플 응답

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "compatible-model-preview-test",
  "description": "Description of the knowledge base.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "outputMode": "extractiveData",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "kind": "openAICompatible",
      "openAICompatibleParameters": {
        "uri": "https://model-gateway.contoso.com/teams/catalog/chat/completions?route=primary&api-version=2026-01-01",
        "modelName": "gpt-4.1-mini",
        "managedIdentityAudience": "11111111-2222-3333-4444-555555555555"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "isServiceLevelKey": false,
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "tags": {
    "businessUnit": "Contoso Engineering Department",
    "costCenter": "ABC-123",
    "owner": "Contoso"
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  },
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  },
  "tools": [
    {
      "name": "product-search",
      "description": "Search product documentation.",
      "knowledgeSources": [
        {
          "name": "ks-preview-test",
          "alwaysQuerySource": false,
          "filterAddOn": "id ne null",
          "maxOutputDocuments": 50,
          "failOnError": true
        }
      ],
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "retrieveDefaults": {
        "maxRuntimeInSeconds": 30,
        "maxOutputDocuments": 2,
        "maxOutputSizeInTokens": 5000
      }
    }
  ]
}

정의

속성 Description
Accept

Accept 헤더입니다.

AzureOpenAIModelName

호출될 Azure Open AI 모델 이름입니다.

AzureOpenAIVectorizerParameters

Azure OpenAI 리소스에 연결하기 위한 매개 변수를 지정합니다.

CorsOptions

인덱스에 대한 CORS(원본 간 리소스 공유)를 제어하는 옵션을 정의합니다.

ErrorAdditionalInfo

리소스 관리 오류 추가 정보

ErrorDetail

오류 세부 정보입니다.

ErrorResponse

실패한 작업에 대한 오류 세부 정보를 반환하는 모든 Azure Resource Manager API에 대한 일반적인 오류 응답입니다. 또한 OData 오류 응답 형식을 따릅니다.

KnowledgeBase

지식 기반 정의를 나타냅니다.

KnowledgeBaseAzureOpenAIModel

쿼리 계획을 수행하는 데 사용되는 Azure OpenAI 리소스를 지정합니다.

KnowledgeBaseMicrosoftRetriever1Model

쿼리 계획 및 검색에 사용되는 Microsoft Retriever 1을 지정합니다.

KnowledgeBaseModelKind

쿼리 계획에 사용할 AI 모델입니다.

KnowledgeBaseOpenAICompatibleModel

지식 기반 검색이나 최소 모드 지식 소스 이미지 구체화를 위한 고객 제어 OpenAI 호환 모델을 지정합니다. 검색 시 모델 프로필은 채팅 완료 또는 응답을 선택합니다. Standard/CU 추출이나 웹 지식 소스가 포함된 지식 베이스에는 지원되지 않습니다.

KnowledgeBaseOpenAICompatibleParameters

OpenAI 호환 채팅 완료 또는 응답 엔드포인트의 연결 매개변수. 생성하려면 비어 있지 않은 헤더 또는 managedIdentityAudience 중 정확히 하나가 필요합니다. 업데이트는 변경 없는 연결 및 모델 프로필에 대한 자격 증명을 유지하기 위해 헤더를 생략할 수 있습니다.

KnowledgeBaseRetrieveDefaults

지식 기반 검색 요청에 대한 요청 전체 기본값이 지속됩니다. 각 값은 매칭되는 검색-요청 필드의 기본값을 제공합니다; 서비스 기본값은 설정되지 않았을 때 적용되고, 요청 시간 값이 있을 때는 우선권을 가집니다.

KnowledgeBaseTool

고객이 제공한 설명과 지식 기반 소스 일부를 포함하는 이름 있는 검색 도구.

KnowledgeBaseToolKnowledgeSourceReference

기존 지식 소스와 선택된 영구 검색 기본값 부분집합에 대한 참조이며, 전체 요청 시간 매개변수 모델이 아닙니다. 참조된 소스가 종류를 결정합니다; 지식 베이스가 저장될 때 호환되지 않는 기본값은 거부됩니다. 명시적인 검색 요청 값이 우선권을 가지며, 필터는 AND와 결합되어 있습니다.

KnowledgeRetrievalAutoReasoningEffort

검색 시 자동으로 추론 노력을 선택하세요. 서비스는 모든 요청을 가장 저렴한 티어에서 시딩하고, 필요한 만큼만 서비스 최대 이용 가능한 티어까지 에스컬레이션합니다.

KnowledgeRetrievalLowReasoningEffort

낮은 추론 노력으로 지식 검색을 실행합니다.

KnowledgeRetrievalMediumReasoningEffort

중간 추론 노력으로 지식 검색을 실행합니다.

KnowledgeRetrievalMinimalReasoningEffort

최소한의 추론 노력으로 지식 검색을 실행합니다.

KnowledgeRetrievalOutputMode

이 검색에 대한 출력 구성입니다.

KnowledgeRetrievalReasoningEffortKind

검색 중에 사용할 작업량입니다.

KnowledgeSourceReference

지식 출처에 대한 언급.

SearchIndexerDataNoneIdentity

데이터 원본의 ID 속성을 지웁니다.

SearchIndexerDataUserAssignedIdentity

사용할 데이터 원본의 ID를 지정합니다.

SearchResourceEncryptionKey

Azure Key Vault의 고객 관리형 암호화 키입니다. 만들고 관리하는 키를 사용하여 인덱스 및 동의어 맵과 같은 미사용 데이터를 암호화하거나 복호화할 수 있습니다.

Accept

Accept 헤더입니다.

값 Description
application/json;odata.metadata=minimal

AzureOpenAIModelName

호출될 Azure Open AI 모델 이름입니다.

값 Description
text-embedding-ada-002

TextEmbeddingAda002 모델.

text-embedding-3-large

TextEmbedding3Large 모델.

text-embedding-3-small

TextEmbedding3Small 모델.

gpt-4o

GPT4o 모델입니다.

gpt-4o-mini

GPT4oMini 모델입니다.

gpt-4.1

GPT41 모델입니다.

gpt-4.1-mini

GPT41Mini 모델입니다.

gpt-4.1-nano

GPT41Nano 모델입니다.

gpt-5

GPT5 모델입니다.

gpt-5-mini

GPT5미니 모델입니다.

gpt-5-nano

Gpt5Nano 모델입니다.

gpt-5.1

GPT51 모델입니다.

gpt-5.2

GPT52 모델입니다.

gpt-5.4

GPT54 모델입니다.

gpt-5.4-mini

GPT54미니 모델입니다.

gpt-5.4-nano

GPT54Nano 모델입니다.

gpt-5.5

GPT55 모델입니다.

gpt-5.6-sol

GPT56Sol 모델입니다.

gpt-5.6-terra

Gpt56Terra 모델입니다.

gpt-5.6-luna

GPT56Luna 모델입니다.

gpt-6-astra

Gpt6Astra 모델.

gpt-6-sol

Gpt6Sol 모델.

gpt-6-luna

Gpt6Luna 모델.

gpt-6.1-sol

Gpt61Sol 모델.

AzureOpenAIVectorizerParameters

Azure OpenAI 리소스에 연결하기 위한 매개 변수를 지정합니다.

속성 형식 Description
apiKey

string

지정된 Azure OpenAI 리소스의 API 키입니다.

authIdentity SearchIndexerDataIdentity:

아웃바운드 연결에 사용되는 사용자 할당 관리 ID입니다.

deploymentId

string

지정된 리소스에 대한 Azure OpenAI 모델 배포의 ID입니다.

modelName

AzureOpenAIModelName

제공된 deploymentId 경로에 배포되는 포함 모델의 이름입니다.

resourceUri

string (uri)

Azure OpenAI 리소스의 리소스 URI입니다.

CorsOptions

인덱스에 대한 CORS(원본 간 리소스 공유)를 제어하는 옵션을 정의합니다.

속성 형식 Description
allowedOrigins

string[]

JavaScript 코드에 인덱스에 대한 액세스 권한이 부여되는 원본 목록입니다. {protocol}://{fully-qualified-domain-name}[:{port#}] 형식의 호스트 목록 또는 모든 출처를 허용하는 단일 '*'를 포함할 수 있습니다(권장되지 않음).

maxAgeInSeconds

integer (int64)

브라우저가 CORS 프리플라이트 응답을 캐시해야 하는 기간입니다. 기본값은 5분입니다.

ErrorAdditionalInfo

리소스 관리 오류 추가 정보

속성 형식 Description
info

추가 정보입니다.

type

string

추가 정보 유형입니다.

ErrorDetail

오류 세부 정보입니다.

속성 형식 Description
additionalInfo

ErrorAdditionalInfo[]

오류 추가 정보

code

string

오류 코드입니다.

details

ErrorDetail[]

오류 세부 정보입니다.

message

string

오류 메시지입니다.

target

string

오류 대상.

ErrorResponse

실패한 작업에 대한 오류 세부 정보를 반환하는 모든 Azure Resource Manager API에 대한 일반적인 오류 응답입니다. 또한 OData 오류 응답 형식을 따릅니다.

속성 형식 Description
error

ErrorDetail

오류 개체입니다.

KnowledgeBase

지식 기반 정의를 나타냅니다.

속성 형식 Description
@odata.etag

string

기술 자료의 ETag입니다.

answerInstructions

string

답변을 생성할 때 지식 기반에서 고려하는 지침들.

corsOptions

CorsOptions

지식 베이스의 교차 원산 자원 공유(CORS) 제어 옵션.

description

string

기술 자료에 대한 설명입니다.

encryptionKey

SearchResourceEncryptionKey

Azure Key Vault에서 만드는 암호화 키에 대한 설명입니다.

knowledgeSources

KnowledgeSourceReference[]

이 지식 베이스에서 참조하는 지식 출처.

models KnowledgeBaseModel[]:

AI 모델에 연결하는 방법에 대한 구성 옵션이 포함되어 있습니다.

name

string

기술 자료의 이름.

outputMode

KnowledgeRetrievalOutputMode

지식 기반의 출력 모드입니다.

retrievalInstructions

string

쿼리 계획을 개발할 때 지식 베이스에서 고려하는 지침들.

retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

검색 추론 노력 구성.

retrieveDefaults

KnowledgeBaseRetrieveDefaults

이 지식 기반의 지속적인 요청 전체 조회 기본값입니다. 이 값들은 해당 필드가 생략된 요청을 가져오는 데 적용됩니다; 존재할 경우 요청 시간 값이 우선권을 가집니다.

tags

object

지식 베이스를 분류하고 사용 및 비용을 부여하기 위한 사용자 정의 키-값 쌍.

tools

KnowledgeBaseTool[]

명명된 검색 도구들로, 각각 이 지식 기반의 일부 출처로 제한됩니다. 구성이 이루어지면, MCP는 전체 지식 기반에서 데이터를 가져오는 내장 knowledge_base_retrieve 도구와 더불어 이러한 도구들을 광고합니다. 이 API 버전에서 도구를 누락하거나 빈 배열을 제공하면 기존 도구가 삭제됩니다.

KnowledgeBaseAzureOpenAIModel

쿼리 계획을 수행하는 데 사용되는 Azure OpenAI 리소스를 지정합니다.

속성 형식 Description
azureOpenAIParameters

AzureOpenAIVectorizerParameters

Azure OpenAI parameters.

kind string:

azureOpenAI

쿼리 계획에 사용할 AI 모델입니다.

KnowledgeBaseMicrosoftRetriever1Model

쿼리 계획 및 검색에 사용되는 Microsoft Retriever 1을 지정합니다.

속성 형식 Description
kind string:

microsoftRetriever1

쿼리 계획에 사용할 AI 모델입니다.

KnowledgeBaseModelKind

쿼리 계획에 사용할 AI 모델입니다.

값 Description
azureOpenAI

쿼리 계획에 Azure Open AI 모델을 사용합니다.

openAICompatible

지식 기반 검색이나 지식 소스 이미지 구체화를 위해 고객이 직접 제어하는 OpenAI 호환 엔드포인트를 사용하세요.

microsoftRetriever1

쿼리 계획 및 검색을 위해 Microsoft Retriever 1을 사용하세요.

KnowledgeBaseOpenAICompatibleModel

지식 기반 검색이나 최소 모드 지식 소스 이미지 구체화를 위한 고객 제어 OpenAI 호환 모델을 지정합니다. 검색 시 모델 프로필은 채팅 완료 또는 응답을 선택합니다. Standard/CU 추출이나 웹 지식 소스가 포함된 지식 베이스에는 지원되지 않습니다.

속성 형식 Description
kind string:

openAICompatible

쿼리 계획에 사용할 AI 모델입니다.

openAICompatibleParameters

KnowledgeBaseOpenAICompatibleParameters

OpenAI 호환 엔드포인트의 연결 및 인증 매개변수.

KnowledgeBaseOpenAICompatibleParameters

OpenAI 호환 채팅 완료 또는 응답 엔드포인트의 연결 매개변수. 생성하려면 비어 있지 않은 헤더 또는 managedIdentityAudience 중 정확히 하나가 필요합니다. 업데이트는 변경 없는 연결 및 모델 프로필에 대한 자격 증명을 유지하기 위해 헤더를 생략할 수 있습니다.

속성 형식 Description
authIdentity SearchIndexerDataIdentity:

managedIdentityAudience 토큰을 획득하는 데 사용된 사용자 할당 관리 신원입니다. 검색 서비스의 시스템 할당 신원을 사용하지 않습니다. managedIdentityAudience에서만 허용됩니다.

headers

object (password)

엔드포인트 인증을 위한 비어 있지 않은 HTTP 헤더가 저장됩니다. 이름과 값 모두 비밀이며 응답에서 절대 반환되지 않습니다. 빈 지도는 유효하지 않습니다. managedIdentityAudience 및 authIdentity와 상호 독점적입니다. 업데이트 시, 생략된 헤더는 동일한 리소스와 모델 바인딩에서만 보존되며, 이는 정확한 엔드포인트, 모델 프로필 및 인증 ID가 변경되지 않은 경우에만 적용됩니다; 그렇지 않으면 새로운 자격 증명을 제공하세요.

managedIdentityAudience

string

관리형 신원 인증을 위한 고객의 서드파티 Microsoft Entra 애플리케이션의 기본 애플리케이션 GUID. api:// 접두사나 /.default 접미사는 포함하지 마십시오. 헤더와 상호 배타적인 경우.

modelName

AzureOpenAIModelName

검색의 기능과 한계를 결정하는 지원되는 채팅 모델 이름입니다. 지식 소스 이미지 구상의 경우, 이는 요청 본문의 모델 선택자로 전송됩니다; URI 경로는 이 이름과 관계없이 채팅 완료 또는 응답을 선택합니다. 지식 기반 검색을 위해 GPT-6 모델 프로필은 응답을 사용하고, 기존 모델 프로필은 채팅 완료를 사용합니다; 엔드포인트는 선택한 프로토콜을 지원해야 하며, 응답에 대한 상태 없는 도구 연속성을 포함해야 합니다. 검색 요청 본문은 모델을 생략합니다; URI 또는 게이트웨이는 실제 모델을 선택하고 필요한 공급자 모델 식별자를 제공합니다. 임베딩 모델과 임의 공급자 프로토콜은 지원되지 않습니다.

uri

string (uri)

경로 및 쿼리 매개변수를 포함한 완전한 HTTPS POST URL. 경로나 API 버전을 추가하지 않고 변경 없이 전송됨; 리디렉션은 따르지 않습니다. 지식 기반 검색을 위해서는 엔드포인트가 모델 프로필의 채팅 완료 또는 응답 프로토콜을 수용해야 합니다. 지식 소스 이미지 구체화를 위해 URI 경로는 /chat/completions 또는 /response로 끝나야 합니다; 쿼리 매개변수는 프로토콜을 선택하지 않습니다.

KnowledgeBaseRetrieveDefaults

지식 기반 검색 요청에 대한 요청 전체 기본값이 지속됩니다. 각 값은 매칭되는 검색-요청 필드의 기본값을 제공합니다; 서비스 기본값은 설정되지 않았을 때 적용되고, 요청 시간 값이 있을 때는 우선권을 가집니다.

속성 형식 Description
maxOutputDocuments

integer (int32)

검색 출력에 기본 최대 문서 수가 있습니다.

maxOutputSizeInTokens

integer (int32)

리트리브 출력에 포함된 콘텐츠의 기본 최대 크기(토큰 단위)입니다.

maxRuntimeInSeconds

integer (int32)

검색 요청의 기본 최대 실행 시간은 초 단위입니다.

KnowledgeBaseTool

고객이 제공한 설명과 지식 기반 소스 일부를 포함하는 이름 있는 검색 도구.

속성 형식 Description
description

string

minLength: 1
maxLength: 1024

도구를 사용할 때 설명하는 빈 것이 아니며, 최대 1024자입니다. MCP 카탈로그에 그대로 광고됨.

knowledgeSources

KnowledgeBaseToolKnowledgeSourceReference[]

고유한 소스 참조의 비어 있지 않은 목록입니다. 각 출처는 지식 기반에 속해야 합니다. 서로 다른 도구가 같은 출처를 참조할 수 있습니다.

name

string

minLength: 2
maxLength: 64
pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])$

고유하고 대소문자를 구분하는 도구 이름입니다. 앞뒤 하이픈이 없는 2개에서 64개의 소문자 ASCII 문자, 숫자 또는 하이픈을 포함합니다.

retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

이 도구는 지식 베이스의 추론 노력을 덮어씁니다. 명시적인 검색 요청 값이 우선권을 가집니다.

retrieveDefaults

KnowledgeBaseRetrieveDefaults

이 도구에 대한 지식 기반 기본값을 덮어쓰는 기본값을 검색합니다. 명시적인 검색 요청 값이 우선권을 가집니다.

KnowledgeBaseToolKnowledgeSourceReference

기존 지식 소스와 선택된 영구 검색 기본값 부분집합에 대한 참조이며, 전체 요청 시간 매개변수 모델이 아닙니다. 참조된 소스가 종류를 결정합니다; 지식 베이스가 저장될 때 호환되지 않는 기본값은 거부됩니다. 명시적인 검색 요청 값이 우선권을 가지며, 필터는 AND와 결합되어 있습니다.

속성 형식 Description
alwaysQuerySource

boolean

출처를 조회해야 하는지 여부. MCP 서버 소스에는 지원되지 않습니다. 명시적인 요청 제외가 우선권을 가집니다.

failOnError

boolean

이 소스에서 오류가 발생하면 검색이 실패할지 여부.

filterAddOn

string

검색 인덱스 소스를 위한 추가 OData 필터. 지식 베이스가 저장될 때 지원되지 않는 소스 유형에 대해 거부됩니다. AND를 이용한 소스 및 요청 필터와 결합됩니다.

maxOutputDocuments

integer (int32)

minimum: 50
maximum: 200

이 소스에서 검색되는 최대 문서 수는 50개에서 200개 사이입니다.

name

string

minLength: 1

지식 기반 내 지식 출처의 이름.

rerankerThreshold

number (float)

반환된 문서에 대한 최소 리랭커 점수입니다. 재순위 기능이 활성화되어야 합니다.

KnowledgeRetrievalAutoReasoningEffort

검색 시 자동으로 추론 노력을 선택하세요. 서비스는 모든 요청을 가장 저렴한 티어에서 시딩하고, 필요한 만큼만 서비스 최대 이용 가능한 티어까지 에스컬레이션합니다.

속성 형식 Description
kind string:

auto

추론 노력의 종류입니다.

KnowledgeRetrievalLowReasoningEffort

낮은 추론 노력으로 지식 검색을 실행합니다.

속성 형식 Description
kind string:

low

추론 노력의 종류입니다.

KnowledgeRetrievalMediumReasoningEffort

중간 추론 노력으로 지식 검색을 실행합니다.

속성 형식 Description
kind string:

medium

추론 노력의 종류입니다.

KnowledgeRetrievalMinimalReasoningEffort

최소한의 추론 노력으로 지식 검색을 실행합니다.

속성 형식 Description
kind string:

minimal

추론 노력의 종류입니다.

KnowledgeRetrievalOutputMode

이 검색에 대한 출력 구성입니다.

값 Description
extractiveData

생성적 변경 없이 지식 소스에서 직접 데이터를 반환합니다.

answerSynthesis

응답 페이로드에 대한 답변을 합성합니다.

KnowledgeRetrievalReasoningEffortKind

검색 중에 사용할 작업량입니다.

값 Description
minimal

원본 선택, 쿼리 계획 또는 반복 검색을 수행하지 않습니다.

low

검색 중에 낮은 추론을 사용합니다.

medium

검색하는 동안 적당한 양의 추론을 사용하십시오.

auto

검색 시 자동으로 추론 노력을 선택하며, 가장 저렴한 단계에서만 필요한 만큼만 점차 상승시킵니다.

KnowledgeSourceReference

지식 출처에 대한 언급.

속성 형식 Description
enableFreshness

boolean

이 지식 소스에 대해 신선성 인식 검색을 활성화해야 하는지 여부를 나타냅니다. 신선도가 사실일 경우, 검색 과정에서 신선도 점수 프로필이 적용되어 결과가 새로운 문서에 편향되도록 합니다.

enableImageServing

boolean

이 지식 소스에 대해 이미지 서빙을 활성화해야 하는지 여부를 나타냅니다. 사실일 경우, 인제 중 추출된 이미지는 쿼리 시점에 하위 모델에 전달됩니다.

name

string

참조 자료의 이름입니다.

SearchIndexerDataNoneIdentity

데이터 원본의 ID 속성을 지웁니다.

속성 형식 Description
@odata.type string:

#Microsoft.Azure.Search.DataNoneIdentity

ID 유형을 지정하는 URI 조각입니다.

SearchIndexerDataUserAssignedIdentity

사용할 데이터 원본의 ID를 지정합니다.

속성 형식 Description
@odata.type string:

#Microsoft.Azure.Search.DataUserAssignedIdentity

ID 유형을 지정하는 URI 조각입니다.

federatedIdentityClientId

string

다중 테넌트 User-Assigned 관리 신원 지원: 사용자 지정 관리 신원과 연합되도록 구성된 멀티텐턴트 앱의 클라이언트 ID.

userAssignedIdentity

string

일반적으로 검색 서비스에 할당되어야 하는 "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" 형식으로 사용자 할당 관리 ID의 정규화된 Azure 리소스 ID입니다.

SearchResourceEncryptionKey

Azure Key Vault의 고객 관리형 암호화 키입니다. 만들고 관리하는 키를 사용하여 인덱스 및 동의어 맵과 같은 미사용 데이터를 암호화하거나 복호화할 수 있습니다.

속성 형식 Default value Description
accessCredentials.applicationId

string

미사용 데이터를 암호화할 때 사용할 Azure Key Vault에 필요한 액세스 권한이 부여된 AAD 애플리케이션 ID입니다. 애플리케이션 ID는 AAD 애플리케이션의 개체 ID와 혼동해서는 안 됩니다.

accessCredentials.applicationSecret

string

지정된 AAD 애플리케이션의 인증 키입니다.

identity SearchIndexerDataIdentity:

이 암호화 키에 사용할 명시적 관리 ID입니다. 지정하지 않고 액세스 자격 증명 속성이 null이면 시스템 할당 관리 ID가 사용됩니다. 리소스 업데이트 시 명시적 ID가 지정되지 않은 경우 변경되지 않은 상태로 유지됩니다. "none"을 지정하면 이 속성의 값이 지워집니다.

isServiceLevelKey

boolean

False

이 키가 서비스 수준 키인지 여부를 나타내는 선택적 값입니다. 기본값은 false입니다.

keyVaultKeyName

string

미사용 데이터를 암호화하는 데 사용할 Azure Key Vault 키의 이름입니다.

keyVaultKeyVersion

string

미사용 데이터를 암호화하는 데 사용할 Azure Key Vault 키의 버전입니다.

keyVaultUri

string

미사용 데이터를 암호화하는 데 사용할 키를 포함하는 DNS 이름이라고도 하는 Azure Key Vault의 URI입니다. 예제 URI는 https://my-keyvault-name.vault.azure.net수 있습니다.