구조적 응답 템플릿

아티클
10/24/2023

적용 대상: SDK v4

구조화된 응답 템플릿을 통해 개발자는 템플릿, 컴퍼지션 등 LG(Language Generation)의 광범위한 기능을 지원하는 복잡한 구조를 정의할 수 있으며, 구조화된 응답의 해석은 LG 라이브러리의 호출자에게 맡깁니다.

봇 애플리케이션의 경우 다음과 같은 지원이 제공됩니다.

활동 정의
카드 정의

Bot Framework 활동 템플릿에는 사용자 지정 가능한 여러 필드가 포함되어 있습니다. 다음 속성은 가장 일반적으로 사용되며 활동 템플릿 정의를 통해 구성할 수 있습니다.

속성	사용 사례
Text	시각적으로 렌더링하기 위해 채널에서 사용하는 텍스트 표시
말하기	음성으로 렌더링하기 위해 채널에서 사용하는 음성 텍스트
첨부 파일	해당 유형의 첨부 파일 목록입니다. 채널에서 UI 카드 또는 기타 제네릭 파일 첨부 파일 형식으로 렌더링하는 데 사용됩니다.
SuggestedActions	사용자에게 제안으로 렌더링되는 작업 목록입니다.
InputHint	음성 입력을 지원하는 디바이스에서 오디오 캡처 스트림 상태를 제어합니다. 가능한 값에는 포함 `accepting`, `expecting`또는 `ignoring`.

템플릿 확인자에서 구현하는 기본 대체 동작은 없습니다. 속성을 지정하지 않으면 지정되지 기본. 예를 들어 Speak 속성만 Text 지정된 경우 속성이 속성으로 자동으로 할당 Text 되지 않습니다.

정의

구조적 템플릿의 정의는 다음과 같습니다.

# TemplateName
> this is a comment
[Structure-name
    Property1 = <plain text> .or. <plain text with template reference> .or. <expression>
    Property2 = list of values are denoted via '|'. e.g. a | b
> this is a comment about this specific property
    Property3 = Nested structures are achieved through composition
]

기본 텍스트 템플릿의 예는 다음과 같습니다.

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

제안된 동작이 있는 텍스트의 예는 다음과 같습니다. 목록을 나타내는 데 사용합니다 | .

> With '|' you are making attachments a list.
# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    SuggestedActions = 10 | 20 | 30
]

Hero 카드 정의의 예는 다음과 같습니다.

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

참고 항목

LG는 SDK 카드 정의에 맞게 변환되는 카드 정의에 약간의 가변성을 제공합니다. 예를 들어 SDK 카드 정의에서만 images 지원되더라도 LG의 모든 카드 정의에서 필드와 images 필드가 모두 image 지원됩니다.

HeroCard 또는 썸네일 카드 모든 imageimages 필드에 정의된 값은 결합되어 생성된 카드 이미지 목록으로 변환됩니다. 다른 유형의 카드 경우 템플릿에서 마지막으로 정의된 값이 필드에 할당 image 됩니다. 필드에 할당하는 image/images 값은 문자열, 적응 식 또는 다음을 사용하는 |형식의 배열일 수 있습니다.

다음은 이전 템플릿의 조합입니다.

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
    Attachments = ${HeroCard()}
    SuggestedActions = 10 | 20 | 30
    InputHint = expecting
]

# GetAge
- how old are you?
- what is your age?

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

기본적으로 모든 템플릿 참조는 구조화된 템플릿을 평가하는 동안 한 번 평가됩니다.

예를 들어 속성 # AskForAge.prompt 과 Text 속성 모두 Speak 에 대해 동일한 해상도 텍스트를 반환합니다.

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

구조화된 템플릿 내의 각 참조에 대해 새 평가를 요청하는 데 사용할 <TemplateName>!() 수 있습니다.

아래 예제에서는 각 인스턴스에서 GetAge가 다시 평가되기 때문에 Speak 및 Text에는 다른 해결 텍스트가 있을 수 있습니다.

[Activity
    Text = ${GetAge()}
    Speak = ${GetAge!()}
]

# GetAge
- how old are you?
- what is your age?

회전식 카드를 표시하는 방법은 다음과 같습니다.

# AskForAge.prompt
[Activity
> Defaults to carousel layout in case of list of cards
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
]

# AskForAge.prompt_2
[Activity
> Explicitly specify an attachment layout
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
    AttachmentLayout = list
]

# HeroCard (title, subtitle, text)
[Herocard
    title = ${title}
    subtitle = ${subtitle}
    text = ${text}
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

이스케이프 문자로 \를 사용합니다.

> You can use '\' as an escape character
> \${GetAge()} would not be evaluated as expression, would be parsed as '${getAge()}' string
# AskForAge.prompt
[Activity
        Text = \${GetAge()}
        SuggestedActions = 10 \| cards | 20 \| cards
]

구조적 템플릿 컴퍼지션

구조화된 템플릿에서 지원되는 컴퍼지션 동작은 다음과 같습니다.

컴퍼지션은 구조 컨텍스트를 인식합니다. 참조되는 대상 템플릿이 구조화된 템플릿인 경우 구조체 형식이 일치해야 합니다. 예를 들어 ActivityTemplate을 다른 ActivityTemplate에서 참조할 수 있습니다.
단순 또는 조건부 응답 템플릿에 대한 참조는 구조화된 템플릿 내의 모든 위치에 존재할 수 있습니다.

다음 템플릿이 있다고 가정합니다.

# T1
[Activity
    Text = ${T2()}
    Speak = foo bar ${T3().speak}
]

# T2
- This is awesome

# T3
[Activity
    Speak = I can also speak!
]

evaluateTemplate('T1')을 호출하면 다음과 같은 내부 구조체가 생성됩니다.

[Activity
    Text = This is awesome
    Speak = I can also speak!
]

다른 구조적 템플릿에 대한 전체 참조

다른 구조적 템플릿에 대한 참조를 다른 구조적 템플릿의 속성으로 포함하거나 다른 단순 또는 조건부 응답 템플릿의 참조로 포함할 수 있습니다.

다른 구조적 템플릿에 대한 전체 참조의 예는 다음과 같습니다.

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
]

이 콘텐츠를 사용하여 호출하면 evaluateTemplate('ST1') 다음과 같은 내부 구조가 생성됩니다.

[MyStruct
    Text = foo
    Speak = bar
]

호출 템플릿과 호출된 템플릿 모두에 동일한 속성이 있는 경우 호출자의 콘텐츠는 호출된 템플릿의 모든 콘텐츠를 덮어씁니다.

예를 들면 다음과 같습니다.

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
    Text = zoo
]

이 컨텍스트를 통해 evaluateTemplate('ST1')을 호출하면 다음과 같은 내부 구조체가 생성됩니다.

[MyStruct
    Text = foo
    Speak = bar
]

이 컴퍼지션 스타일은 루트 수준에서만 존재할 수 있습니다. 속성 내에 다른 구조적 템플릿에 대한 참조가 있는 경우 해결 방법은 해당 속성에 대한 컨텍스트입니다.

첨부 파일의 외부 파일 참조 구조화

파일을 외부에서 참조하는 데 사용되는 두 가지 미리 빌드된 함수가 있습니다.

fromFile(fileAbsoluteOrRelativePath)는 지정된 파일을 로드합니다. 이 함수에서 반환된 콘텐츠는 콘텐츠 평가를 지원합니다. 템플릿 참조, 속성 및 식이 평가됩니다.
ActivityAttachment(content, contentType) 는 콘텐츠에 contentType 아직 지정되지 않은 경우를 설정합니다.

이러한 두 가지 미리 빌드된 함수를 사용하면 모든 카드 유형을 포함하여 외부에서 정의된 모든 콘텐츠를 끌어올 수 있습니다. 다음 구조화된 LG를 사용하여 작업을 작성합니다.

# AdaptiveCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'adaptiveCard')}
]

# HeroCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'heroCard')}
]

아래와 같이 첨부 파일을 사용할 수도 있습니다.

# AdaptiveCard
[Attachment
    contenttype = adaptivecard
    content = ${json(fromFile('../../card.json'))}
]

# HeroCard
[Attachment
    contenttype = herocard
    content = ${json(fromFile('../../card.json'))}
]

추가 정보

C# API 참조
JavaScript API 참조
적응형 도구를 사용하여 디버그를 읽고 템플릿을 분석하고 디버그하는 방법을 알아봅니다.

Share via

구조적 응답 템플릿

정의

구조적 템플릿 컴퍼지션

다른 구조적 템플릿에 대한 전체 참조

첨부 파일의 외부 파일 참조 구조화

추가 정보

추가 리소스