스킬 트레이너 FAQ

Classic/VPC 환경에서 이용 가능합니다.

스킬 트레이너를 사용하면서 발생할 수 있는 문제와 해결 방법에 대해 설명합니다.

스킬셋

Q. 스킬셋 하나에 몇 개의 스킬을 생성할 수 있나요?
A. 10개까지 생성할 수 있습니다. 단, 스킬 정보(API Spec, Manifest)에 저장된 글자 수에 따라 데이터 수집 단계에서 토큰 수 초과 오류가 발생될 수 있습니다.

Q. 스킬셋 답변 형식을 설정했는데, 데이터 수집 시 최종 답변에 제대로 적용되지 않는 것 같습니다.
A. 스킬과 유저 쿼리의 복잡도에 따라 설정한 답변 형식이 최종 답변에 제대로 적용되지 않을 수 있습니다. 이런 경우, 데이터 수집 화면에서 최종 답변을 직접 수정한 뒤 학습을 수행해 보십시오.
예를 들어, 스킬셋의 답변 형식을 '포맷: JSON 형식'이라고 설정했지만 실제로 모델이 생성한 '최종 답변 A' 형태인 경우, '최종 답변 B' 형태로 수정하여 저장해 주십시오. 이런 유형의 데이터를 여러 건 수집한 뒤 학습을 진행하면 개선된 답변을 받을 수 있습니다.

• 최종 답변 A

  2023년 8월 9일 기준 모자 쇼핑 구매 전환 이용자 수는 다음과 같습니다. 페이지 뷰 수는 1,003,120, 이용자 수는 1,222,334입니다.
  

• 최종 답변 B

  {
     "20230809":{
        "purchase":[
           {
              "pv":"1,003,120",
              "user":"1,222,334"
           }
        ]
     }
  }
  

스킬

Q. 스킬 제작에 필요한 API를 개발하고자 합니다. API 개발 시 주의 사항이 있을까요?
A. API를 개발할 때는 사용자가 예상 가능하고 유용한 검색(필터링) 조건을 파라미터로 활용하는 것을 권장합니다. 만약 역할이 비슷하거나 겹치는 파라미터(예시: 글 작성자, 글 수정자, 태그된 사용자, 댓글 작성자)가 있다면, 스킬의 정확도가 떨어질 수 있습니다. 또한 API 응답이 긴 경우 토큰 수 초과 오류를 방지하기 위해 페이지네이션 파라미터를 함께 설계해 주실 것을 권장합니다. 그리고 원활한 데이터 수집 및 서비스 적용을 위하여 사전에 API 호출 시 필수 파라미터 여부를 점검해 주십시오.

Q. API Spec에서 description을 영어로 작성해도 되나요?
A. 영어로 작성하는 것도 가능합니다. 하지만 모델의 성능을 최대한 활용하기 위해 한국어로 작성하는 것을 권장합니다.

Q. 파라미터 description에는 어떤 내용을 작성하면 되나요?
A. 파라미터 description에는 예시를 작성해 주십시오. 예시가 있으면 모델이 description에 작성된 예시를 기반으로 더 정확한 액션 입력 값을 생성할 수 있습니다.

{
    "date": {
        "type": "string",
        "description": "기준 일자를 의미합니다. 형식은 yyyymmdd를 사용합니다. <예시> 20230101, 20231121, 20210403"
    }
}

Q. API 호출 시 URL을 path 방식으로 구성해도 되나요?
A. API URL은 argument 방식으로 구성하는 것을 권장합니다. 스킬 모델에 사용되는 학습 데이터가 모두 argument 방식이므로 path 방식으로 구성 시 모델의 성능을 보장할 수 없습니다.

Q. 스킬 Endpoint URL에 입력해야 하는 포트가 정해져 있나요?
A. 별도의 포트 제한은 없습니다. 다만, Endpoint 관련하여 통신 이슈나 모델의 성능 이슈로 인해 오류가 발생할 수 있습니다. 문제가 계속 발생할 경우, 화면을 캡처하여 문의해 주십시오.

Q. 스킬의 Endpoint URL은 https만 지원하나요?
A. Endpoint URL은 http와 https를 모두 지원합니다.

Q. Multi-path API가 잘 작동하려면 Description for model을 어떻게 작성해야 하나요?
A. Description for model은 하나의 스킬 내에 여러 path가 있는 경우, 유저 쿼리에 적절한 path를 선택하기 위한 정보로 사용됩니다. 따라서 path별 역할에 대해 자세히 작성해야 하며 path별로 검색될 키워드를 작성해야 합니다.
다음과 같이 path 정보와 parameter 정보를 분리하여 명시하면 언어 모델의 성능이 향상될 수 있습니다. 이때 operationId가 아닌 path가 명시되어야 합니다.

<작성 예시>
음료를 조회할 때는 /sample_api/beverage을 사용하세요. 이 API는 음료명을 검색어로 입력할 때 잘 작동합니다. 주류를 조회할 때는 /sample_api/liquor를 사용하세요. 이 API는 주류명을 검색어로 입력할 때 잘 작동합니다. 일별 할인 품목을 조회할 때는 /sample/event를 사용하세요. 이 API는 날짜를 검색어로 입력할 때 동작하며, 검색 날짜는 무조건 yyyymmdd 형식으로 입력합니다.

데이터 수집

Q. 데이터 수집 시 최대 몇 번의 스킬 호출을 수행할 수 있나요?
A. 데이터 수집 시에는 스킬 호출 횟수에 제한이 없습니다. 단, 스킬셋 답변 생성 API를 통한 호출은 최대 4번까지 가능하며, 이를 초과할 경우 최종 답변이 생성되지 않을 수 있습니다.

Q. 액션 입력 생성 결과가 의도한 대로 나오지 않습니다. 의도한 대로 모델이 액션 입력을 생성하게 하려면 어떻게 해야 하나요??
A. API Spec에서 파라미터의 'description'에 예시를 추가해 주십시오. 예시가 있으면 언어 모델이 API Spec을 기반으로 유저 쿼리를 이해하여 올바른 파라미터를 갖춘 URL을 생성할 수 있습니다.
<작성 예시>

{
    "keyword": {
        "type": "string",
        "description": "수식어를 의미하며, 관형어와 부사어의 형태입니다. <예시> 친절한, 만족스러운, 좋은",
    },
    "review": {
        "type": "string",
        "description": "긍부정 선호도. <예시> pos, neg 둘 중 하나의 값"
    }
}

Q. 데이터 수집 시 '플래닝 가능한 스킬이 없습니다'라는 오류 메시지가 나타납니다. 참고로 스킬은 '완료'로 저장된 상태입니다.
A. 모델이 스킬의 API Spec 또는 Manifest를 제대로 이해하지 못한 경우 발생하는 오류입니다. API Spec 및 Manifest 작성 가이드에 따라 모델이 충분히 이해할 수 있도록 다시 작성해 주십시오. 문제가 계속 발생할 경우, 고객 지원에 문의해 주십시오.

Q. 데이터 수집 시 '토큰 수 초과' 오류 메시지가 나타납니다. 토큰이 얼마나 초과되었는지 확인할 수 있나요?
A. 데이터 수집 시 단계별로 최대 토큰 수가 4,096으로 제한되어 있습니다. 토큰 수를 계산하려면 CLOVA Studio의 익스플로러 > 토큰 계산기(HCX)를 이용해 주십시오.
각 단계별로 합산되는 값은 다음과 같습니다.

Q. 호출 옵션은 데이터 수집할 때마다 매번 초기화되나요?
A. 호출 옵션을 적용하여 데이터 수집을 진행한 후, 다음 데이터 수집을 위해 [초기화] 버튼을 클릭하더라도 호출 옵션은 그대로 유지됩니다. 단, 데이터 수집 화면에서 벗어난 후에 데이터 수집 화면에 다시 접속한 경우에는 호출 옵션이 초기화됩니다. 이런 경우 불러오기 기능으로 임시저장한 작업을 불러오면 이전에 사용한 호출 옵션을 함께 불러올 수 있습니다.

용도에 따른 호출 옵션 작성 예시가 궁금합니다.
A. 스킬셋 내에 등록된 모든 API에 대해 호출 옵션을 일괄 적용하고자 할 때 baseOperation 필드를 활용할 수 있습니다. 작성 예시는 다음과 같습니다.

{
  "baseOperation": {
    "query": {
      "serviceKey": "value"
    }
  }
}

특정 Operation ID에 한하여 호출 옵션을 적용하고자 할 때 operations 필드를 활용할 수 있습니다. 작성 예시는 다음과 같습니다.

{
  "operations": [
    {
      "operationId": "filterBakeryProducts",
      "query": {
        "serviceKey": "value"
      }
    }
  ]
}

baseOperation 필드와 operations 필드를 함께 적용하는 것도 가능합니다. 작성 예시는 다음과 같습니다.

{
  "baseOperation": {
    "header": {
      "baseHeader": "baseHeaderValue"
    },
    "query": {
      "baseQuery": "baseQueryValue"
    },
    "requestBody": {
      "baseBody": "baseBodyValue"
    }
  },
  "operations": [
    {
      "operationId": "testOperationId1",
      "header": {
        "header1": "headerValue1"
      },
      "query": {
        "query1": "queryValue1"
      },
      "requestBody": {
        "body1": "bodyValue1"
      }
    },
    {
      "operationId": "testOperationId2",
      "header": {
        "header2": "headerValue2"
      },
      "query": {
        "query2": "queryValue2"
      },
      "requestBody": {
        "body2": "bodyValue2"
      }
    }
  ]
}

Q. 데이터 수집 작업 중에 오류가 발생했습니다. 로그를 어떻게 확인할 수 있나요?
A. 작업 중 오류가 발생하면 다음 정보와 함께 문의를 남겨 주십시오. 해결 방법을 안내해 드리겠습니다.

• 오류 화면(스크린숏)
• 스킬셋
• 스킬 정보

Q. 유저 쿼리에 필수 파라미터가 누락되었을 때 모델이 누락된 파라미터에 대해 재질의 하는 답변을 생성할 수 있나요?
A. 네 가능합니다. API 설계 시 필수 파라미터가 누락된 경우, 오류 코드(ex. HTTP 상태코드 400)를 반환하지 않고 정상 코드(ex. HTTP 상태코드 200)로 반환하도록 해야 합니다. 대신 누락된 파라미터를 알려주는 메시지를 함께 반환하는 것이 좋습니다. 이렇게 하면 최종 답변 영역에서 모델이 누락된 파라미터를 요청하는 질문을 생성하고, 원하는 형식으로 튜닝 및 학습도 진행할 수 있습니다.

<데이터 수집 예시>

데이터 학습

Q. 데이터 학습 시에는 모델에게 주로 어떤 내용을 학습시키나요?
A. 데이터 학습은 스킬 호출 학습과 최종 답변 학습으로 구분됩니다.

• 스킬 호출 학습: 사용자 요청을 수행하기 위한 API URL 및 파라미터를 모델이 정확하게 생성하지 못한 경우, 이를 의도에 맞게 수정한 뒤 데이터를 저장하면 학습을 통해 모델이 개선됩니다. 데이터를 수정할 때는 사용자 요청과 무관한 키워드를 필드에 포함해서는 안됩니다.
• 최종 답변 학습: 스킬 호출 결과를 바탕으로 최종 답변을 생성하는 과정에서 모델이 일부 정보를 누락하거나 답변의 스타일(양식, 어투 등)을 변경하고자 하는 경우, 이를 의도에 맞게 수정한 뒤 데이터를 저장하면 학습을 통해 모델이 개선됩니다. 이때 스킬 호출 결과에 나타나지 않은 정보를 임의로 최종 답변에 포함해서는 안됩니다.

버전 관리

Q. 스킬셋 버전은 최대 몇 개까지 생성할 수 있나요?
A. 스킬셋 버전은 300개까지 저장할 수 있습니다.

Q. 버전의 갱신 기준이 무엇인가요?
A. 스킬셋 버전이 생성되거나 갱신되는 기준은 다음과 같습니다.

• 스킬셋에 신규 스킬 최초 생성 시 스킬셋의 'v1'이 생성됩니다.
• 스킬셋 내 새로운 스킬을 생성하면 버전이 갱신됩니다.
• 스킬셋 내에 등록된 스킬을 삭제하면 버전이 갱신됩니다. 버전 메모에 삭제 이력이 남습니다.
• 기존 스킬을 편집하고 저장하면 버전이 갱신됩니다.
• 데이터 학습이 완료되면 버전이 갱신됩니다.