Bixby Developer Center

Guides
References

빠른 시작 가이드

나만의 캡슐을 생성할 준비가 되었으면 이 빠른 시작 가이드를 따라 시작해 보세요.

이 가이드에서는 Bixby 플랫폼의 기본적인 사항을 살펴보고 다음을 수행하는 방법을 배울 수 있습니다.

  • concept 및 action을 통해 캡슐의 구성 요소(building blocks) 추가. concept은 캡슐의 구성 요소(building blocks)를 생성하고, action은 실제로 수행되는 작업을 정의합니다.
  • action에 대한 JavaScript 구현. 이러한 JavaScript는 캡슐의 계산을 수행합니다.
  • dialog 및 view 추가. dialog는 Bixby가 사용자와 인터랙션하는 방식을 결정하며, view는 디자인 요소로서 정보가 표시되는 방식을 결정합니다.
  • Bixby가 training을 통해 사용자의 말과 질문을 이해하도록 훈련.

그럼 이제 시작해 볼까요? 이 가이드에서는 주사위 캡슐을 생성해보도록 하겠습니다. 이때 사용자는 던질 주사위 개수와 각 주사위의 면 수를 선택할 수 있습니다. 예를 들어, 사용자가 "roll 2 6-sided dice"라고 말하면 Bixby는 주사위 던지기 결과로 나온 각 주사위의 숫자와 숫자의 합계로 응답합니다.

Bixby Developer Studio 다운로드 및 설치

  1. Bixby Developer Studio를 다운로드하고 설치합니다. 최소 시스템 요구 사항을 비롯한 Bixby Developer Studio에 대한 자세한 내용은 Bixby Developer Studio 사용을 참조하십시오.

  2. Bixby Developer Studio를 시작하고 Log In button을 클릭합니다. Bixby Developer Studio에 삼성 인증 페이지가 표시됩니다.

  3. 삼성 계정 자격 증명을 사용하여 로그인합니다. 로그인에 성공하면 인증 페이지에 Login successful이 표시됩니다.

  4. 인증 페이지에 있는 launch button을 선택합니다. Bixby Developer Studio가 시작되고 연결 및 워크스페이스를 준비합니다. Bixby Developer Studio의 왼쪽 아래에 Ready가 표시되면 시작할 준비가 된 것입니다.

캡슐 생성

Bixby Developer Studio를 설치했으면 이제 캡슐을 생성할 수 있습니다. Bixby는 concept과 action을 사용하여 사용자 인텐트(intent)를 파악하고 goal을 정합니다. 그런 다음 해당 goal을 달성하기 위한 plan을 생성하며, 이 과정에서 새로운 프로그램을 작성합니다. Bixby는 이 프로그램을 실행하여 다음으로 무엇을 할지를 결정합니다. 즉, 결과를 보여주거나, 사용자와 인터랙션하거나, 아니면 다른 plan을 작성 및 실행할 수 있습니다.

첫 번째 단계는 새로운 캡슐을 생성하는 것입니다. 원래는 Bixby Developer Studio에서 File > New Capsule을 사용하여 캡슐을 생성해야 하지만 처음 배우는 과정이므로 미리 만들어 둔 파일을 사용하겠습니다. 시작하기 전에, Bixby GitHub 리포지토리에서 이 샘플 캡슐의 파일을 다운로드하고 추출하거나 이 리포지토리를 복제합니다.

주사위 샘플 캡슐 GitHub 리포지토리: https://github.com/bixbydevelopers/capsule-sample-dice/

캡슐을 복제하거나 추출했으면 File > Open Capsule을 사용하여 캡슐을 엽니다.

Concept 및 Action 추가

캡슐을 열었으니 이제 자세히 살펴보겠습니다. 먼저 concept과 action에 대해 살펴보겠습니다. Concept과 action은 캡슐의 구성 요소(building blocks)입니다. Concept은 Bixby가 알고 있는 것을 의미하며 변수 또는 input으로 생각할 수 있습니다. Action은 Bixby가 할 수 있는 것을 결정하며 동사 또는 메서드로 생각할 수 있습니다. 이 주사위 캡슐의 경우, dice/models/에서 concept과 action이 포함된 다음과 같은 파일을 확인할 수 있습니다.

  • primitives: 원시 타입(primitives)은 integers, booleans, decimals, text와 같은 단순 type을 나타냅니다. 이 캡슐의 모든 원시 타입(primitives)은 integer들입니다.
    • NumDice.model.bxb: 한 번에 던지는 주사위 수를 나타내는 integer
    • NumSides.model.bxb: 각 주사위의 면 수를 나타내는 integer
    • Roll.model.bxb: 각 주사위 던지기의 결과를 나타내는 integer
    • Sum.model.bxb: 주사위를 던져 나온 모든 숫자의 합계를 나타내는 integer
  • structures: 구조체 concept은 여러 원시 컨셉(primitive concept)이 포함된 레코드입니다.
    • RollResult.model.bxb: 키(key)-value 객체를 추적하는 데 사용되며, 한 번 또는 여러 번의 주사위 던지기 결과를 나타내고 sumroll 속성을 포함합니다. 여러 번 주사위를 던지는 경우 roll property가 둘 이상의 value를 취할 수 있습니다.
  • actions:
    • RollDice.model.bxb: 두 가지 input(numDicenumSides)을 받아 RollResultConcept type의 output을 생성하는 action을 포함합니다. 개발자는 action을 통해 Bixby가 사용자를 위해 수행할 수 있는 오퍼레이션(operation)을 정의할 수 있습니다.

이러한 concept 중 numDice(NumDiceConcept type)와 numSides(NumSidesConcept type)는 이 캡슐이 동작하는 데 필수적인 두 가지 input입니다.

NumDiceConcept concept을 정의하는 NumDice.model.bxb 파일을 자세히 살펴보겠습니다.

integer (NumDiceConcept) {
description (The number of dice to throw.)
}

View on GitHub

여기서는 NumDiceConcept이 integer로 설정되어 있고 설명이 포함되어 있음을 알 수 있습니다. primitives 폴더에 있는 다른 파일에도 대부분 이와 매우 유사한 코드가 들어 있습니다.

예외적으로 RollResult.model.bxb에는 sumroll을 추적하는 데 사용되는 구조체 concept이 들어 있습니다. 첫 번째 property는 던진 모든 주사위의 총 합계에 해당하며, 두 번째 property는 각 주사위 던지기의 목록을 포함합니다. RollDice 호출 후에 각 property를 사용할 수 있어야 하므로 둘 다 필수입니다(min (Required)). sum 값은 하나만 있지만(max (One)), roll property는 주사위를 던질 때마다 하나씩 생성되어 결국 여러 개의 value를 가질 수 있으므로 max (Many)를 사용합니다.

structure (RollResultConcept) {
description (The result object produced by the RollDice action.)
property (sum) {
type (SumConcept)
min (Required)
max (One)
}
property (roll) {
description (The list of results for each dice roll.)
type (RollConcept)
min (Required)
max (Many)
}
}

View on GitHub

캡슐 테스트

캡슐 파일을 추가했으니 이제 테스트해 볼 수 있습니다.

  1. 시뮬레이터를 엽니다(View > Open Simulator).

  2. Confirm을 클릭하여 NL 모델 컴파일을 실행합니다. 이를 통해 시뮬레이터에서 발화를 테스트할 수 있습니다. 자세한 내용은 training 추가 단계에서 확인할 수 있습니다.

Note

시뮬레이터에서 컴파일을 확인하라는 팝업 창이 표시되지 않을 경우 Capsule 드롭다운 메뉴를 클릭한 후 Confirm을 클릭합니다.

  1. 사용자 요청의 구조화된 표현인 다음 인텐트(intent)를 Input 패널에 입력합니다.

       // Give two values (number of dice and number of sides) with the
    // goal of rolling dice
    intent {
    goal: example.dice.RollResultConcept
    value: example.dice.NumSidesConcept (6)
    value: example.dice.NumDiceConcept (2)
    }
  2. Run Intent button을 선택합니다.

다음과 같은 결과가 표시됩니다.

인텐트(intent) 실행 결과

축하합니다! Bixby에서 첫 캡슐을 테스트했습니다! 위 예에서 주사위 던지기 결과는 각각 54임을 알 수 있습니다.

이제 지금까지 한 작업을 되짚어보도록 하겠습니다. 실행한 인텐트(intent)는 Bixby가 이해할 수 있는 방식으로 표현한 사용자가 원하는 것입니다. 인텐트(intent)에는 최소한 goal이 있어야 하며, 보통은 value도 있습니다. value는 사용자가 제공하는 제약 조건 또는 단서입니다.

시뮬레이터에서 Debug Console button(디버그 콘솔 button))을 눌러 디버그 콘솔을 엽니다. 인텐트(intent)를 실행하면 input(NumDiceConceptNumSidesConcept)과 그에 따른 RollDice action 및 RollResultConcept goal을 보여주는 plan graph가 디버그 콘솔에 생성됩니다.

인텐트(intent) 실행 결과

이 예에서는 Bixby가 하나의 action만 수행하면 되지만 항공권 구입과 같은 다른 경우에는 여러 input과 action이 필요합니다.

그럼 이제, 캡슐에서 필요한 다른 부분을 살펴보겠습니다.

JavaScript(*.js)

Concept과 action이 캡슐의 골격이라면 JavaScript 함수는 근육이라 할 수 있습니다. 이미 주사위 던지기에서 기본적인 계산을 수행하는 JavaScript 파일 RollDice.js를 포함했습니다. 이 JavaScript는 두 가지 input을 받아 난수(random number)를 생성한 다음, 각 주사위 던지기 결과와 합계를 계산합니다.

또한 이 JavaScript에 액세스할 수 있도록 endpoint 선언(endpoints.bxb)을 포함했습니다. 이렇게 하면 로컬 및 원격 JavaScript 함수를 endpoint로 액세스할 수 있습니다.

View(*.view.bxb)

주사위를 던진 후에 Bixby는 view를 통해 결과를 표시하는 방식을 지정합니다. 기본적으로 Bixby는 디버깅에 유용한 제네릭 테이블(generic table)을 생성하지만 이 테이블은 사용자가 보기에 좋지 않습니다. 이 예에서는 사전 작성된 두 개의 input view 파일(NumDice_Input.view.bxbNumDSides_Input.view.bxb)이 제공되었습니다. 또한 빈 결과 view 파일(RollResult.view.bxb)도 포함되어 있는데, 개발자는 이 파일을 통해 사용자에게 주사위 던지기 결과를 표시할 방식을 커스터마이즈하게 됩니다.

Dialog(*.dialog.bxb)

사용자가 Bixby에게 말할 때 Bixby가 응답하는 방식을 dialog 파일을 통해 커스터마이즈할 수 있습니다. Dialog는 사용자에게 무슨 일이 이루어지는지를 알려줍니다. View와 마찬가지로 Bixby는 제네릭 다이얼로그(generic dialog)를 생성하므로 dialog 파일(NumDice.dialog.bxb, NumSides.dialog.bxbRollResult.dialog.bxb)을 활용해 주사위 던지기를 보다 자세하게 커스터마이즈해야 합니다.

Training

이 가이드의 시작 부분에서는 인텐트(intent)를 사용하여 쿼리를 실행했습니다. 하지만 실제로 사용자는 "roll 2 4-sided dice" 또는 "roll some dice"와 같은 자연어를 사용하여 대화합니다. 따라서 주사위 던지기에서 Bixby가 자연어 발화를 처리할 수 있도록 몇 가지 training 예제를 추가해야 합니다.

View 추가

먼저, 결과를 보기 좋게 표시할 수 있도록 view를 추가하겠습니다.

  1. resources/en/views 폴더의 파일 탐색기에서 RollResult.view.bxb를 엽니다.

  2. 다음 코드를 추가합니다.

     result-view {
    match {
    RollResultConcept (rollResult)
    }

    render {
    layout {
    section {
    content {
    single-line {
    text {
    style (Detail_M)
    value ("Sum: #{value(rollResult.sum)}")
    }
    }
    single-line {
    text {
    style (Detail_M)
    value ("Rolls: #{value(rollResult.roll)}")
    }
    }
    }
    }
    }
    }
    }

    사용자 인터페이스는 다양한 방식으로 설정할 수 있습니다. 이 예에서는 결과를 표시하므로 result-view를 사용합니다. 주사위 던지기 결과는 value 키(keys)에 포함됩니다. 이러한 키(keys)는 Expression Language를 사용하여 rollResult.sum(합계)과 rollResult.roll(개별 주사위 던지기 결과)의 value를 표시합니다.

    RollResultConcept을 표시할 때 매치 패턴(match pattern)이 여러 view 중에서 어떻게 이 view가 선택되는지를 결정합니다. 매치 패턴(match pattern)에 대한 자세한 내용은 개발자 가이드에 나와 있습니다.

  3. View를 추가한 후에 시뮬레이터에서 인텐트(intent)를 한 번 더 실행합니다.

     // Give two values (number of dice and number of sides) with the
    // goal of rolling dice
    intent {
    goal: example.dice.RollResultConcept
    value: example.dice.NumSidesConcept (6)
    value: example.dice.NumDiceConcept (2)
    }
Note

시뮬레이터를 오랫동안 사용하지 않으면 세션 시간이 초과될 수 있습니다. 새 컨버세이션(conversation)을 시작하려면 기본 시뮬레이터 창을 클릭합니다. 캡슐 내용이 동기화되지 않은 상태라는 경고가 표시될 경우 드롭다운 메뉴에서 해당 캡슐을 선택하고 Confirm을 클릭하여 수동으로 다시 컴파일할 수 있습니다. 또한 Reset button을 클릭하여 Bixby와의 컨버세이션(conversation)을 재설정하고 컨텍스트를 지울 수 있습니다.

이제 업데이트된 view가 결과에 표시됩니다.

새 layout 결과

Dialog 추가

다음으로, 몇 가지 dialog를 추가하여 Bixby가 주사위 던지기 내에서 다양한 concept을 지칭하는 방식을 개선해 보겠습니다. Layout은 Bixby가 정보를 표시하는 방식을 커스터마이즈하는 데 사용할 수 있는 반면, dialog는 텍스트 자체를 커스터마이즈하는 데 사용할 수 있습니다.

  1. 파일 탐색기에서 NumSides.dialog.bxb를 엽니다.

  2. 다음 코드를 추가합니다.

     dialog (Concept) {
    match {
    // Look for this type
    NumSidesConcept
    }
    // Use the following template text with this type
    template ("number of sides")
    }

    View 파일과 마찬가지로 이 dialog는 매치 패턴(match pattern)을 사용하여 NumSidesConcept type을 찾고 해당 concept의 기본 dialog를 템플릿 텍스트(template text)로 대체합니다. 이제 다른 dialog 세트를 추가하여 Bixby가 결과를 반환하는 방식을 변경해 보겠습니다.

  3. 파일 탐색기에서 NumDice.dialog.bxb를 엽니다.

  4. 다음 코드를 추가합니다.

     dialog (Concept) {
    match {
    // Look for this type
    NumDiceConcept
    }
    // Use this template text with this type
    template ("number of dice")
    }
  5. 파일 탐색기에서 RollResult.dialog.bxb를 엽니다.

  6. 랜덤 dialog를 추가하는 다음 코드를 추가합니다.

     dialog (Result) {
    // bind the variable "rollResult" to the result
    match {
    RollResultConcept (rollResult)
    }
    // define a condition that changes the dialog depending on whether there
    // is one or more dice rolls
    if (size(rollResult.roll) == 1) {
    template ("You've got a ${value(rollResult.roll)}!!!")
    }
    else-if (size(rollResult.roll) > 1) {
    choose (Random) {
    template ("The sum is ${value(rollResult.sum)}")
    template ("You rolled ${list(rollResult.roll, 'value')}")
    }
    }
    }

    여기서는 사용자가 지정하는 주사위 수가 하나인지 둘 이상인지에 따라 정확한 dialog를 표시하기 위해 조건 if 규칙(rule)을 사용하고 있습니다.

  7. Dialog를 추가한 후에 시뮬레이터에서 인텐트(intent)를 한 번 더 실행합니다.

     // Give two values (number of dice and number of sides) with the goal of
    // rolling dice
    intent {
    goal: example.dice.RollResultConcept
    value: example.dice.NumSidesConcept (6)
    value: example.dice.NumDiceConcept (2)
    }

이제 위에 나온 두 template 텍스트 중 하나를 무작위로 선택하여 다음 결과와 비슷하게 업데이트된 dialog가 표시됩니다.

인텐트(intent) 실행 결과

인텐트(intent) 실행 결과

Training 예제 추가

마지막으로, Bixby가 다양한 사용자 input을 이해할 수 있도록 몇 가지 자연어 training 예제를 추가해 보겠습니다.

  1. 캡슐에서 resources 폴더를 연 다음 en 하위 폴더를 열고 training을 선택합니다.

  2. 학습 도구 상단의 Adding New Training에서 다음 발화를 추가하고 Add를 클릭합니다.

     roll 2 6-sided dice

    add training

  3. 다음 텍스트를 Goal로 추가합니다.

     RollResultConcept
  4. NL 필드에서 2를 선택하고 Node 필드에 NumDiceConcept을 입력한 다음 Done을 클릭합니다.

    숫자 선택

  5. NL 필드에서 6을 선택하고 Node 필드에 NumSidesConcept을 입력한 다음 Done을 클릭합니다.

    add training

  6. Save를 클릭합니다.

Training 테스트

Training 예제를 추가했으니 이제 이 training에 적용되는 발화를 Bixby가 학습할 수 있도록 NL(자연어) 모델을 컴파일해야 합니다. Compile NL Model button을 클릭하고 모델이 컴파일될 때까지 기다립니다.

시뮬레이터로 돌아와서 다음 발화를 추가하고 Run NL을 클릭합니다.

roll 2 6-sided dice

이제 추가한 발화가 시뮬레이터에서 실행됩니다. "roll 4 8-sided dice"와 같은 다양한 변형(variation)을 시뮬레이터 input box에 입력합니다.

이 training에서는 주사위 수와 면 수의 기본값을 활용하지 않습니다. 지금까지 training을 추가한 유일한 발화에 둘 다 포함되어 있기 때문입니다. 이러한 경우를 처리하는 새 training 예제를 직접 추가해 보세요.

선택 단계

이로써 training이 포함된, 제대로 동작하는 캡슐이 생성되었습니다. 이제 몇 가지 선택 단계를 따라 하면 기본 input 값을 제공하고 잘못된 input이 있는지 확인하여 더 똑똑한 주사위 캡슐을 만들 수 있습니다.

기본값 추가(선택 사항)

현재는 주사위 던지기가 두 가지 input, 즉 주사위 수와 주사위 면 수를 지정하는 경우에만 작동합니다. 그런데 사용자가 이러한 숫자를 지정하지 않는 경우도 있지 않을까요?

Bixby 시뮬레이터에서 value를 지정하지 않은 이 인텐트(intent)를 실행해 보세요.

intent {
goal: example.dice.RollResultConcept
}

이 경우 Bixby는 goal을 달성하는 데 필요한 최소한의 input을 획득하기 위해 사용자에게 value를 물어봅니다. 이 문제를 해결하려면 캡슐에 default-init를 사용해 기본값을 추가하여 사용자가 value를 지정하지 않을 때 Bixby가 자동으로 value를 제공하도록 합니다.

  1. 파일 탐색기에서 RollDice.model.bxb를 엽니다.

  2. 현재 코드를 다음 코드로 대체합니다.

     action (RollDice) {
    // specify this action as a calculation
    type (Calculation)
    // add a required input for the number of dice that defaults to 2.
    collect {
    input (numDice) {
    type (NumDiceConcept)
    min (Required)
    max (One)
    // add a default value of two dice
    default-init {
    intent {
    goal {NumDiceConcept}
    value {
    NumDiceConcept (2)
    }
    }
    }
    }
    // add a required input for the number of sides that defaults to 6.
    input (numSides) {
    type (NumSidesConcept)
    min (Required)
    max (One)
    // add a default value of six sides per dice
    default-init {
    intent {
    goal {NumSidesConcept}
    value {
    NumSidesConcept (6)
    }
    }
    }
    }
    }
    // set the output of this action to "RollResultConcept"
    output (RollResultConcept)
    }
  3. 이제 동일한 인텐트(intent)를 다시 실행합니다.

     intent {
    goal: example.dice.RollResultConcept
    }

사용자가 value를 지정하지 않을 때 채워지는 기본값을 추가했으므로 이제 Bixby가 사용자에게 value를 물어보지 않습니다.

인텐트(intent) 실행 결과

Input 유효성 검사(validation) 추가(선택 사항)

마지막으로, 사용자가 주사위 던지기에 지정한 value가 유효한지 확인하겠습니다. 예를 들어 사용자가 면이 하나인 주사위 0개를 지정한다면 문제가 됩니다.

  1. RollDice.model.bxb를 엽니다.

  2. 현재 코드를 다음 코드로 대체합니다.

       action (RollDice) {
    type (Calculation)
    collect {
    input (numDice) {
    type (NumDiceConcept)
    min (Required)
    max (One)
    default-init {
    intent {
    goal { NumDiceConcept }
    value {
    NumDiceConcept (2)
    }
    }
    }
    // add a validation dialog prompt when the user indicates less
    // than 1 dice.
    validate {
    if (numDice < 1) {
    prompt {
    dialog {
    template ("You must have at least one dice.")
    }
    }
    }
    }
    }
    input (numSides) {
    type (NumSidesConcept)
    min (Required)
    max (One)

    default-init {
    intent{
    goal { NumSidesConcept }
    value {
    NumSidesConcept (6)
    }
    }
    }
    // add a validation dialog prompt when the user indicates less
    // than 2 sides.
    validate {
    if (numSides < 2) {
    prompt {
    dialog {
    template ("A dice must have at least 2 sides.")
    }
    }
    }
    }
    }
    }
    output (RollResultConcept)
    }

    이 코드에는 validate가 포함되어 있고, 여기에 특정 숫자를 검사하는 if 문이 포함되어 있습니다.

  3. 면과 주사위 숫자가 유효하지 않은 다음 인텐트(intent)를 사용하여 방금 추가한 내용을 테스트합니다.

     intent {
    goal: example.dice.RollResultConcept
    value: example.dice.NumSidesConcept (1)
    value: example.dice.NumDiceConcept (0)
    }

이제 보다 유용한 프롬프트가 포함된 메시지가 표시됩니다.

잘못된 인텐트(intent) 실행

관련 항목

이제 concept, action, JavaScript, dialog, layout, 기본값, 유효성 검사(validation), training이 모두 포함된 첫 캡슐이 생성되었습니다. 참고로 이 가이드에서는 이러한 각 구성 요소의 기본적인 사항만을 다루고 있습니다.

코드 다루는 것을 좋아하신다면 샘플 캡슐에서 Bixby 플랫폼에 대해 자세히 알아볼 수 있습니다.

시각적인 방식으로 학습하는 것을 선호하시면 초급부터 고급까지 다양한 주제를 다룬 수많은 Bixby 비디오 중에서 원하는 비디오를 재생해 보세요.

더 많은 내용을 읽어보고 싶으시면 개발자 가이드의 다양한 섹션에서 자세한 내용을 살펴볼 수 있습니다. 다음은 Bixby 플랫폼을 심층적으로 다루고 있는 항목의 몇 가지 예입니다.