생성형 AI 프롬프트 기술

메모

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

Microsoft 이외의 모델에 지원되는 직접 또는 API Management 연결에 적용되는 용어는 타사 모델을 참조하세요.

GenAI(생성 AI) 프롬프트 스킬은 Azure Foundry Models 또는 Microsoft Foundry에 배포된 대형 언어 모델(LLM)에 대해 Chat 완료 요청을 실행합니다. 이 기술을 활용해 색인화하고 검색 가능한 콘텐츠로 저장할 수 있는 새로운 정보를 생성하세요.

다음은 GenAI 프롬프트 스킬이 콘텐츠 제작에 어떻게 도움이 될 수 있는지 몇 가지 예시입니다:

  • 이미지 언어화
  • 긴 텍스트 구절을 요약하세요
  • 복잡한 내용을 단순화하세요
  • 프롬프트에서 명확히 표현할 수 있는 다른 어떤 작업이든 수행하세요

일반적으로 사용 가능한 GenAI 프롬프트 기술 기능은 2026-10-01 Search Service REST API 를 사용합니다. 이 기술은 이를 지원하는 Azure SDK 사용할 수도 있습니다. 이 기술은 텍스트, 이미지, 그리고 PDF 파일에서 추출한 시각적 이미지와 텍스트가 포함된 멀티모달 콘텐츠를 지원합니다.

Tip

이 기술을 데이터 청크 기술과 결합하는 경우가 흔합니다. 멀티모달 튜토리얼은 두 가지 다른 데이터 청킹 전략을 사용한 이미지 언어화를 시연합니다.

지원되는 모델

  • Microsoft Foundry에 배포된 채팅 완성 유추 모델을 사용하여 기술의 입력 및 생성 매개 변수를 허용합니다. 기술에서 사용하는 매개 변수 및 응답 형식을 지원하는 채팅 완료 작업을 구성합니다.

  • 이미지 언어화의 경우, 이미지를 분석하는 데 사용하는 모델이 지원하는 이미지 형식을 결정합니다.

  • GPT-5 모델의 경우, temperature 이 매개변수는 이전 모델들과 같은 방식으로 지원되지 않습니다. 정의가 되어 있다면, 다른 값이 오류를 일으킬 수 있으므로 로 설정 1.0해야 합니다.

  • 청구는 사용하는 모델의 가격에 따라 결정됩니다.

메모

모델 호출은 적격 프라이빗 실행 경로를 구성하지 않는 한 퍼블릭 엔드포인트를 사용합니다. API Management 연결 자격을 참조하세요. 배포 위치를 선택할 때 foundry IQ(Azure AI 검색) 지역 및 Azure OpenAI 모델 지역을 확인합니다.

사전 요구 사항

  • Azure 파운드리 모델의 OpenAI 리소스 또는 Foundry 프로젝트.

  • 귀하의 리소스나 프로젝트에 배포된 지원 모델 .

    • Azure OpenAI의 경우 전체 채팅 완료 호출 URIhttps://<resource-name>.openai.azure.com/openai/deployments/<deployment-name>/chat/completions?api-version=<downstream-api-version>의 기반으로 도메인이 있는 리소스 엔드포인트 openai.azure.com 를 사용합니다. 배포 이름 및 다운스트림 API 버전을 Azure OpenAI 배포에서 지원하는 값으로 바꿉니다. 리소스 기본 엔드포인트가 아닌 이 전체 URL로 설정합니다 uri . 다운스트림 API 버전은 Search API 버전과 별개입니다.

    • Foundry의 경우 작업 경로 및 필요한 쿼리 매개 변수를 포함하여 배포의 전체 채팅 완료 대상 URI를 uri사용합니다.

  • 인증은 Foundry나 Azure OpenAI 리소스에서 API 키를 통해 키 기반으로 할 수 있습니다. 그러나 역할에 할당된 Foundry IQ 서비스 관리 ID 를 사용하여 역할 기반 액세스를 권장합니다.

    • Azure OpenAI 배포의 경우 Cognitive Services OpenAI 사용자를 Foundry IQ 서비스의 시스템 할당 또는 선택한 사용자 할당 관리 ID에 할당합니다. 배포를 호스트하고 구성된 엔드포인트를 프로젝트 개체 또는 Foundry IQ 서비스가 아닌 범위로 소유하는 Azure OpenAI 또는 부모 Foundry/Azure AI Services 리소스를 사용합니다.

    • 지원되는 다른 Foundry 호스팅 모델 엔드포인트의 경우 해당 모델 연결에 필요한 리소스 범위의 관리 ID에 Foundry 사용자를 할당합니다.

      Important

      Foundry RBAC 역할의 이름이 최근에 바뀌었습니다. Foundry User, Foundry OwnerFoundry 계정 소유자 및 Foundry Project Manager는 이전에 Azure AI 사용자, Azure AI 소유자, Azure AI 계정 소유자 및 Azure AI Project Manager로 이름이 지정되었습니다. 이름 바꾸기가 롤아웃되는 동안 일부 위치에서는 이전 이름이 계속 표시될 수 있습니다. 역할 ID 및 핵심 권한은 이름 바꾸기에 의해 변경되지 않습니다.

    • API Management가 검색 인증을 종료하고 자체 백 엔드 ID를 사용하는 경우 게이트웨이에서 검색 권한을 부여합니다. 대신 모델 호스팅 리소스의 해당 게이트웨이 ID에 모델 역할을 할당합니다. 역할 범위 및 ID 식별자를 참조하세요.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

데이터 제한

Limit Notes
maxTokens 기본 기준은 1024 입니다. 최대 값은 모델에 따라 다릅니다.
요청 시간 제한 30초로 고정됨. 벌크 인덱싱 모델을 선택할 때 이 한계를 고려하세요. 추론 모델(예: o1, o3)이 이를 초과할 수 있기 때문입니다.
이미지 Base 64 인코딩된 이미지와 이미지 URL을 지원합니다. 크기 제한은 모델에 따라 다릅니다.

기술 매개 변수

재산 Type 필수 Notes
uri string 예 작업 경로 및 필요한 쿼리 매개 변수를 포함하여 모델 호출 URL을 완료합니다. 지원되는 리소스 도메인은 openai.azure.com, services.ai.azure.comcognitiveservices.azure.com및 models.ai.azure.com. API Management 기본 및 사용자 지정 게이트웨이 도메인도 지원됩니다. 게이트웨이 기본 URL만으로는 전체 작업 URL이 아닙니다. 프로토콜, 인증 및 프라이빗 연결 자격은 Foundry IQ 모델 호출과 함께 API Management 사용을 참조하세요. 사용 권한 사용 SharePoint 인덱서는 SharePoint 권한이 있는 제한을 참조하세요.
apiKey string Cond.* 모델의 비밀 키. 관리 신원을 사용할 때는 빈칸으로 남겨두세요.
authIdentity object Cond.* SearchIndexerDataIdentity 클라이언트 ID 문자열이 아닌 연결된 사용자 할당 관리 ID를 선택하는 개체입니다. 에서 ID의 리소스 IDuserAssignedIdentity를 사용하고 @odata.type: "#Microsoft.Azure.Search.DataUserAssignedIdentity" 사용합니다. 이 속성을 생략하고 apiKey 시스템 할당 ID를 사용합니다. 관리 ID를 참조하세요.
commonModelParameters object No , , 등과 같은 temperaturemaxTokens표준 생성 제어가 있습니다.
extraParameters object No 오픈 사전이 기본 모델 API로 전달됩니다.
extraParametersBehavior string No "pass-through" | "drop" | "error" (기본값 "error").
responseFormat object No 모델이 텍스트, 자유 형식 JSON 객체, 또는 강타입 JSON 스키마를 반환할지 제어합니다. responseFormat 페이로드 예제: {responseFormat: { type: text }}, {responseFormat: { type: json_object }}, {responseFormat: { type: json_schema }}

* 또는 서비스의 시스템 할당 ID 중 apiKeyauthIdentity하나만 사용해야 합니다.

키 인증의 경우 .apiKey 관리 ID의 경우 위에서 설명한 시스템 할당 ID 또는 개체를 authIdentity 생략 apiKey 하고 사용합니다.

commonModelParameters 기본값

매개 변수 기본값
model (배포 기본값)
frequencyPenalty 0
presencePenalty 0
maxTokens 1024
temperature 0.7
seed null
stop null

기술 입력

입력 이름 Type 필수 Description
systemMessage string 예 시스템 수준의 지시(예: "당신은 도움이 되는 조수입니다.").
userMessage string 예 사용자 프롬프트입니다.
text string No 선택적 텍스트가 (텍스트 전용 시나리오)에 userMessage 추가됩니다.
image string (베이스 64 데이터-URL) No 프롬프트에 이미지를 추가합니다(멀티모달 모델만).
imageDetail 문자열 (low | high | auto) No Azure OpenAI 멀티모달 모델에 대한 충실도 힌트입니다.

기술 성과

출력 이름 Type Description
response 문자열 또는 JSON 객체 모델 출력은 요청된 형식으로 진행됩니다 responseFormat.type.
usageInformation JSON 개체 토큰 수와 모델 파라미터의 에코.

샘플 정의

텍스트 전용 요약

이 전체 기술 예제에서는 문서 콘텐츠를 요약하고 생성된 응답에 레이블을 지정하는 선택적 명령을 포함합니다. 엔드포인트, 배포 및 키를 지원되는 모델 구성으로 바꿉다. URL의 Azure OpenAI API 버전은 Search API 버전과는 별개입니다.

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "inputs": [
    { "name": "text", "source": "/document/content" },
    {
      "name": "systemMessage",
      "source": "='You are a concise AI assistant. Begin the response with \"AI-generated content:\".'"
    },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

참조: 기술 세트 - 만들거나 업데이트합니다.

필요에 따라 생성된 텍스트에 레이블 지정

앞의 예제는 .에 배치systemMessage됩니다Begin the response with "AI-generated content:".. 이 명령을 .에 배치할 수도 있습니다 userMessage. 고유한 표현, 배치 및 언어를 선택하거나 표시할 필요가 없는 경우 명령을 생략합니다.

모델 지침은 다를 수 있습니다. 모든 응답에 레이블이 있어야 하는 경우 프롬프트에만 의존하지 않고 애플리케이션에서 레이블을 결정적으로 추가하거나 유효성을 검사합니다. Foundry IQ는 공개 텍스트를 자동으로 삽입하지 않습니다.

이 선택적 표시 텍스트는 컴퓨터에서 확인할 수 있는 출처, 워터마크, 콘텐츠 자격 증명 또는 C2PA 구현이 아닙니다. 법적 또는 규정 준수 요구 사항을 정의하지 않습니다. 지원되는 직접, API Management 및 관리자 연결 모델 구성에도 동일한 프롬프트 접근 방식이 적용됩니다. 모델, 인증, 네트워킹 또는 권한으로 보호되는 보강 제한은 변경되지 않습니다.

텍스트 + 이미지 설명

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Image Describer",
  "context": "/document/normalized_images/*",
  "inputs": [
    { "name": "image", "source": "/document/normalized_images/*/data" },
    { "name": "imageDetail", "source": "=high" },
    { "name": "systemMessage", "source": "='You are a useful AI assistant.'" },
    { "name": "userMessage", "source": "='Describe this image:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  },
  "responseFormat": { "type": "text" }
}

구조화된 수치 사실 찾기

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "NumericalFactFinder",
  "context": "/document",
  "inputs": [
    { "name": "systemMessage", "source": "='You are an AI assistant that helps people find information.'" },
    { "name": "userMessage", "source": "='Find all the numerical data and put it in the specified fact format.'"}, 
    { "name": "text", "source": "/document/content" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "responseFormat": {
    "type": "json_schema",
    "jsonSchemaProperties": {
      "name": "NumericalFactObj",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": "{\"facts\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"number\":{\"type\":\"number\"},\"fact\":{\"type\":\"string\"}},\"required\":[\"number\",\"fact\"]}}}",
        "required": [ "facts" ],
        "additionalProperties": false
      }
    }
  }
}

샘플 출력 (단축)

{
  "response": {
    "facts": [
      { "number": 32.0, "fact": "Jordan scored 32 points per game in 1986-87." },
      { "number": 6.0,  "fact": "He won 6 NBA championships." }
    ]
  },
  "usageInformation": {
    "usage": {
      "completion_tokens": 203,
      "prompt_tokens": 248,
      "total_tokens": 451
    }
  }
}

모범 사례

  • 텍스트 분할 스킬로 긴 문서를 대괄 작성해 모델의 컨텍스트 창 내에 머무르세요.
  • 대용량 인덱싱의 경우, 이 기술에 별도의 모델 배포를 할당하여 쿼리 시 RAG 워크로드의 토큰 할당량에 영향을 주지 않도록 하세요.
  • 대기 시간을 최소화하려면 동일한 Azure 지역에서 모델 및 Foundry IQ 서비스를 공동 배치합니다.
  • 신뢰할 수 있는 구조적 추출과 필드 인덱싱 매핑을 쉽게 하기 위해 responseFormat.json_schema와 함께 사용 하세요.
  • 토큰 사용량을 모니터링하고, 인덱서가 분당 토큰(TPM) 한도를 초과하면 할당량 증가 요청을 제출하세요.

오류 및 경고

Condition 결과
누락 또는 무효 uri Error
인증 방법은 명시되지 않았습니다 Error
둘 다 apiKeyauthIdentity 공급된 제품입니다 Error
지원되지 않는 다중 모드 프롬프트 모델 Error
입력이 모델 토큰 한도를 초과합니다 Error
모델이 대해 유효하지 않은 JSON을 반환합니다. json_schema 경고: 반환된 원시 문자열 response

SharePoint 권한이 있는 제한 사항

인덱서가 SharePoint ACL을 수집할 때 이 기술은 다음과 같은 도메인에서 자사 Azure OpenAI 및 Microsoft Foundry 엔드포인트를 지원합니다. openai.azure.comcognitiveservices.azure.comservices.ai.azure.commodels.ai.azure.com

APIM, 사용자 지정 도메인 및 타사 경로는 인증 또는 네트워크 설정에 관계없이 이 구성에 대해 지원되지 않습니다. ACL 수집을 유지하면서 지원되는 엔드포인트를 사용하거나 선택적 모델 보강을 생략합니다.

민감도 레이블을 ACL과 결합하는 경우를 포함하여 민감도 레이블 수집에서는 이 기술이 지원되지 않습니다.

관리 ID 인증에 대한 보안 고려 사항

GenAI 프롬프트 기술이 관리 ID 인증을 사용하는 경우 Foundry IQ는 Foundry Tools 대상 그룹()에 대한 Microsoft Entra 액세스 토큰을https://cognitiveservices.azure.com 가져오고 지정된 엔드포인트로 전송된 uri요청에 포함합니다. 관리 ID 인증은 설정된 경우 authIdentity 또는 둘 다 apiKey 비어 있고 authIdentity 서비스가 시스템 할당 ID를 사용하는 경우에 적용됩니다.

참조되는 uri 엔드포인트는 사용자 고유의 Azure OpenAI 또는 Foundry 리소스여야 합니다. 지원되는 엔드포인트 도메인은 기술 매개 변수를 참조하세요.

APIM(Azure API Management) 엔드포인트(*.azure-api.net) 및 이러한 리소스 앞에 있는 사용자 지정 도메인도 지원됩니다. 사용자 지정 도메인 또는 APIM 호스트 이름은 이름에서만 확인할 수 없으므로 Foundry IQ는 도메인 일치가 아닌 구성 시간에 라이브 연결 검사를 사용하여 이러한 엔드포인트의 유효성을 검사합니다. 엔드포인트와 Azure OpenAI 또는 Foundry 리소스 간의 관계를 구성하고 유지 관리해야 합니다.

사용 권한 사용 SharePoint 인덱서는 SharePoint 권한이 있는 제한을 참조하세요.

메모

Foundry Tools 대상 그룹에 대해 발급된 관리 ID 토큰은 Id가 권한이 부여된 모든 Foundry 도구 또는 Azure OpenAI 리소스에 대해 유효합니다. 신뢰할 수 없는 엔드포인트로 보내면 토큰이 노출될 수 있습니다.

보안 배포를 유지 관리하려면 다음 방법을 따르세요.

  • 소유하고 신뢰하는 엔드포인트로만 설정합니다 uri . 이전에 나열된 Foundry 도구 도메인을 선호합니다. APIM 또는 사용자 지정 도메인 엔드포인트를 사용하는 경우 관리 ID를 사용하도록 설정하기 전에 자체 리소스 앞에 있는지 확인합니다. 신뢰할 수 있는 호스트 이름은 소유권 증명이 아닙니다.
  • Foundry IQ 서비스에서 사용하는 관리 ID에 최소 권한 원칙을 적용합니다.
    • Azure OpenAI에서 Cognitive Services OpenAI 사용자만 할당합니다.
    • Foundry에서 Foundry 사용자만 할당합니다. 더 광범위한 역할을 부여하지 않습니다.
  • NSP(네트워크 보안 경계) 및 프라이빗 엔드포인트 또는 VNet 통합을 사용하여 Foundry IQ 서비스가 도달할 수 있는 엔드포인트와 대상 리소스가 요청을 수락하는 원본을 제한합니다.
  • APIM 또는 사용자 지정 도메인 엔드포인트를 사용하는 경우 게이트웨이가 인바운드 요청의 유효성을 검사하고 의도한 백 엔드에만 전달해야 합니다. 또한 해당 액세스 정책을 주기적으로 검토해야 합니다.
  • 보다 관리 ID를 apiKey선호합니다. 사용하는 apiKey경우 안전하게 저장 및 회전하고 소스 제어에 포함하지 않습니다. 서비스는 둘 다 apiKeyauthIdentity설정하는 구성을 거부합니다.
  • 기술 세트 정의, 관리 ID 역할 할당 및 APIM 및 사용자 지정 도메인 구성을 주기적으로 검토하여 값, 액세스 제어 및 ID 권한이 최신 상태와 적절한 상태로 유지되도록 uri 합니다. 설정된 변경 관리 및 보안 검토 프로세스를 통해 구성 변경 내용을 검토합니다.
  • Azure OpenAI, Foundry 도구 및 Foundry 로그인 로그, 인증 이벤트 및 액세스 로그를 모니터링하여 예기치 않거나 권한이 없는 활동을 확인합니다.
  • 더 이상 필요하지 않은 사용되지 않는 기술, 엔드포인트, 역할 할당 및 API 키를 제거합니다.

기술 세트 구성에 대한 액세스 제한

기술 세트를 만들거나 수정하거나 실행할 수 있는 사용자는 대상 엔드포인트(uri)와 기술에서 사용하는 인증 구성을 모두 제어합니다. 이 기술은 Foundry Tools 대상 그룹에 대한 관리 ID 토큰을 해당 엔드포인트로 보내기 때문에 이러한 권한을 신뢰할 수 있는 관리자로 제한하고 관리 ID 사용 기술을 구성할 때 표준 변경 관리 및 보안 검토 프로세스를 따릅니다.

참고하십시오