Knowledge Bases - Create Or Update

서비스:: Search Service

API 버전:: 2026-05-01-preview

새로운 지식 베이스를 만들거나 이미 존재하는 지식 베이스를 업데이트합니다.

PUT {endpoint}/knowledgebases('{knowledgeBaseName}')?api-version=2026-05-01-preview

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
endpoint	path	True	string (uri)	검색 서비스의 엔드포인트 URL입니다.
knowledgeBaseName	path	True	string	기술 자료의 이름.
api-version	query	True	string minLength: 1	이 작업에 사용할 API 버전입니다.

요청 헤더

Name	필수	형식	Description
Accept		Accept	Accept 헤더입니다.
If-Match		string	If-Match 조건을 정의합니다. 서버의 ETag가 이 값과 일치하는 경우에만 작업이 수행됩니다.
If-None-Match		string	If-None-Match 조건을 정의합니다. 서버의 ETag가 이 값과 일치하지 않는 경우에만 작업이 수행됩니다.
Prefer	True	Prefer	HTTP PUT 요청의 경우 성공 시 생성/업데이트된 리소스를 반환하도록 서비스에 지시합니다.
x-ms-client-request-id		string (uuid)	요청에 대한 불투명하고 전역적으로 고유한 클라이언트 생성 문자열 식별자입니다.

요청 본문

Name	필수	형식	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[]: KnowledgeBaseAzureOpenAIModel[]	AI 모델에 연결하는 방법에 대한 구성 옵션이 포함되어 있습니다.
outputMode		KnowledgeRetrievalOutputMode	지식 기반의 출력 모드입니다.
retrievalInstructions		string	쿼리 계획을 개발할 때 지식 베이스에서 고려하는 지침들.
retrievalReasoningEffort		KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	검색 추론 노력 구성.

응답

Name	형식	Description
200 OK	KnowledgeBase	요청이 성공했습니다.
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

범위

Name	Description
https://search.azure.com/.default

예제

SearchServiceCreateOrUpdateKnowledgeBase

샘플 요청

HTTP

PUT https://previewexampleservice.search.windows.net/knowledgebases('base-preview-test')?api-version=2026-05-01-preview





{
  "name": "base-preview-test",
  "knowledgeSources": [
    {
      "name": "ks-preview-test"
    }
  ],
  "models": [
    {
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4o-mini"
      },
      "kind": "azureOpenAI"
    }
  ],
  "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.",
  "retrievalInstructions": "Instructions for retrieval for the knowledge base.",
  "answerInstructions": "Instructions for answer synthesis.",
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

샘플 응답

상태 코드:: 200

{
  "@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-4o-mini"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

상태 코드:: 201

{
  "@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-4o-mini"
      }
    }
  ],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

정의

Name	Description
Accept	Accept 헤더입니다.
AzureOpenAIModelName	호출될 Azure Open AI 모델 이름입니다.
AzureOpenAIVectorizerParameters	Azure OpenAI 리소스에 연결하기 위한 매개 변수를 지정합니다.
CorsOptions	인덱스에 대한 CORS(원본 간 리소스 공유)를 제어하는 옵션을 정의합니다.
ErrorAdditionalInfo	리소스 관리 오류 추가 정보
ErrorDetail	오류 세부 정보입니다.
ErrorResponse	실패한 작업에 대한 오류 세부 정보를 반환하는 모든 Azure Resource Manager API에 대한 일반적인 오류 응답입니다. 또한 OData 오류 응답 형식을 따릅니다.
KnowledgeBase	지식 기반 정의를 나타냅니다.
KnowledgeBaseAzureOpenAIModel	쿼리 계획을 수행하는 데 사용되는 Azure OpenAI 리소스를 지정합니다.
KnowledgeBaseModelKind	쿼리 계획에 사용할 AI 모델입니다.
KnowledgeRetrievalLowReasoningEffort	낮은 추론 노력으로 지식 검색을 실행합니다.
KnowledgeRetrievalMediumReasoningEffort	중간 추론 노력으로 지식 검색을 실행합니다.
KnowledgeRetrievalMinimalReasoningEffort	최소한의 추론 노력으로 지식 검색을 실행합니다.
KnowledgeRetrievalOutputMode	이 검색에 대한 출력 구성입니다.
KnowledgeRetrievalReasoningEffortKind	검색 중에 사용할 작업량입니다.
KnowledgeSourceReference	지식 출처에 대한 언급.
Prefer	HTTP PUT 요청의 경우 성공 시 생성/업데이트된 리소스를 반환하도록 서비스에 지시합니다.
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 모델입니다.

AzureOpenAIVectorizerParameters

Object

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

Name	형식	Description
apiKey	string	지정된 Azure OpenAI 리소스의 API 키입니다.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	아웃바운드 연결에 사용되는 사용자 할당 관리 ID입니다.
deploymentId	string	지정된 리소스에 대한 Azure OpenAI 모델 배포의 ID입니다.
modelName	AzureOpenAIModelName	제공된 deploymentId 경로에 배포되는 포함 모델의 이름입니다.
resourceUri	string (uri)	Azure OpenAI 리소스의 리소스 URI입니다.

CorsOptions

Object

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

Name	형식	Description
allowedOrigins	string[]	JavaScript 코드에 인덱스에 대한 액세스 권한이 부여되는 원본 목록입니다. {protocol}://{fully-qualified-domain-name}[:{port#}] 형식의 호스트 목록 또는 모든 출처를 허용하는 단일 '*'를 포함할 수 있습니다(권장되지 않음).
maxAgeInSeconds	integer (int64)	브라우저가 CORS 프리플라이트 응답을 캐시해야 하는 기간입니다. 기본값은 5분입니다.

ErrorAdditionalInfo

Object

리소스 관리 오류 추가 정보

Name	형식	Description
info		추가 정보입니다.
type	string	추가 정보 유형입니다.

ErrorDetail

Object

오류 세부 정보입니다.

Name	형식	Description
additionalInfo	ErrorAdditionalInfo[]	오류 추가 정보
code	string	오류 코드입니다.
details	ErrorDetail[]	오류 세부 정보입니다.
message	string	오류 메시지입니다.
target	string	오류 대상.

ErrorResponse

Object

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

Name	형식	Description
error	ErrorDetail	오류 개체입니다.

KnowledgeBase

Object

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

Name	형식	Description
@odata.etag	string	기술 자료의 ETag입니다.
answerInstructions	string	답변을 생성할 때 지식 기반에서 고려하는 지침들.
corsOptions	CorsOptions	지식 베이스의 교차 원산 자원 공유(CORS) 제어 옵션.
description	string	기술 자료에 대한 설명입니다.
encryptionKey	SearchResourceEncryptionKey	Azure Key Vault에서 만드는 암호화 키에 대한 설명입니다.
knowledgeSources	KnowledgeSourceReference[]	이 지식 베이스에서 참조하는 지식 출처.
models	KnowledgeBaseModel[]: KnowledgeBaseAzureOpenAIModel[]	AI 모델에 연결하는 방법에 대한 구성 옵션이 포함되어 있습니다.
name	string	기술 자료의 이름.
outputMode	KnowledgeRetrievalOutputMode	지식 기반의 출력 모드입니다.
retrievalInstructions	string	쿼리 계획을 개발할 때 지식 베이스에서 고려하는 지침들.
retrievalReasoningEffort	KnowledgeRetrievalReasoningEffort: KnowledgeRetrievalLowReasoningEffort KnowledgeRetrievalMediumReasoningEffort KnowledgeRetrievalMinimalReasoningEffort	검색 추론 노력 구성.

KnowledgeBaseAzureOpenAIModel

Object

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

Name	형식	Description
azureOpenAIParameters	AzureOpenAIVectorizerParameters	Azure OpenAI parameters.
kind	string: azureOpenAI	쿼리 계획에 사용할 AI 모델입니다.

KnowledgeBaseModelKind

열거형

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

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

KnowledgeRetrievalLowReasoningEffort

Object

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

Name	형식	Description
kind	string: low	추론 노력의 종류입니다.

KnowledgeRetrievalMediumReasoningEffort

Object

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

Name	형식	Description
kind	string: medium	추론 노력의 종류입니다.

KnowledgeRetrievalMinimalReasoningEffort

Object

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

Name	형식	Description
kind	string: minimal	추론 노력의 종류입니다.

KnowledgeRetrievalOutputMode

열거형

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

값	Description
extractiveData	생성적 변경 없이 지식 소스에서 직접 데이터를 반환합니다.
answerSynthesis	응답 페이로드에 대한 답변을 합성합니다.

KnowledgeRetrievalReasoningEffortKind

열거형

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

값	Description
minimal	원본 선택, 쿼리 계획 또는 반복 검색을 수행하지 않습니다.
low	검색 중에 낮은 추론을 사용합니다.
medium	검색하는 동안 적당한 양의 추론을 사용하십시오.

KnowledgeSourceReference

Object

지식 출처에 대한 언급.

Name	형식	Description
enableFreshness	boolean	이 지식 소스에 대해 신선성 인식 검색을 활성화해야 하는지 여부를 나타냅니다. 신선도가 사실일 경우, 검색 과정에서 신선도 점수 프로필이 적용되어 결과가 새로운 문서에 편향되도록 합니다.
enableImageServing	boolean	이 지식 소스에 대해 이미지 서빙을 활성화해야 하는지 여부를 나타냅니다. 사실일 경우, 인제 중 추출된 이미지는 쿼리 시점에 하위 모델에 전달됩니다.
name	string	참조 자료의 이름입니다.

Prefer

열거형

HTTP PUT 요청의 경우 성공 시 생성/업데이트된 리소스를 반환하도록 서비스에 지시합니다.

값	Description
return=representation

SearchIndexerDataNoneIdentity

Object

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

Name	형식	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	ID 유형을 지정하는 URI 조각입니다.

SearchIndexerDataUserAssignedIdentity

Object

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

Name	형식	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

Object

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

Name	형식	Default value	Description
accessCredentials.applicationId	string		미사용 데이터를 암호화할 때 사용할 Azure Key Vault에 필요한 액세스 권한이 부여된 AAD 애플리케이션 ID입니다. 애플리케이션 ID는 AAD 애플리케이션의 개체 ID와 혼동해서는 안 됩니다.
accessCredentials.applicationSecret	string		지정된 AAD 애플리케이션의 인증 키입니다.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity		이 암호화 키에 사용할 명시적 관리 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`수 있습니다.