스킬셋 답변 생성

인쇄
공유
PDF

스킬셋 답변 생성

인쇄
공유
PDF

기사 요약

이 요약이 도움이 되었나요?

의견을 보내 주셔서 감사합니다.

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

특정 스킬셋의 API를 호출하여 적절한 답변을 생성합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
POST	/v1/skillsets/{skillset-id}/versions/{version}/final-answer

요청 헤더

헤더에 대한 설명은 다음과 같습니다.

헤더	필수 여부	설명
Authorization	Required	인증을 위한 API 키 (예: `Bearer nv-***********`)
Content-Type	Required	application/json
Accept	Conditional	응답 데이터의 형식 `text/event-stream`
X-NCP-CLOVASTUDIO-REQUEST-ID	Optional	각 요청에 대한 요청 아이디

참고

응답 결과는 기본적으로 JSON 형태로 반환하지만, Accept를 text/event-stream으로 지정 시 스트림 형태로 반환합니다.

요청 경로 파라미터

파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`skillset-id`	String	Required	답변 생성 대상 스킬셋 아이디
`version`	Integer/String	Required	답변 생성 대상 스킬셋 버전 버전 지정하여 스킬셋 사용 시 입력 `{버전 번호}` \| `latest` `{버전 번호}`: 특정 버전 1 ≤ `version` `latest`: 현재 적용된 버전

참고

version은 입력할 스킬셋 버전에 따라 Integer와 String 중에 선택하여 요청해 주십시오.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`query`	String	Required	질의 내용
`tokenStream`	Boolean	Optional	답변 생성 시 토큰 스트리밍 사용 여부 `false` \| `true` `false`: 사용 안 함 `true`: 사용
`chatHistory`	Array	Optional	답변 생성 이력
`chatHistory.role`	Enum	Required	대화 메시지 역할 `user` \| `assistant` `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`chatHistory.content`	String	Required	대화 메시지 내용
`requestOverride`	Object	Optional	모든 API에 적용할 호출 옵션
`requestOverride.baseOperation`	Object	Optional	모든 API에 적용할 호출 옵션 정보
`requestOverride.baseOperation.header`	Object	Optional	모든 API에 적용할 요청 헤더
`requestOverride.baseOperation.query`	Object	Optional	모든 API에 적용할 요청 쿼리 파라미터
`requestOverride.baseOperation.requestBody`	Object	Optional	모든 API에 적용할 요청 바디 GET 메서드 API인 경우 미적용
`requestOverride.operations`	Array	Optional	특정 API에 적용할 호출 옵션

`operations`

operations에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`operationId`	String	Conditional	특정 API의 오퍼레이션 아이디 `operations`를 입력할 경우 필수
`header`	Object	Optional	특정 API에 적용할 요청 헤더
`query`	Object	Optional	특정 API에 적용할 요청 쿼리 파라미터
`requestBody`	Object	Optional	특정 API에 적용할 요청 바디 GET 메서드 API인 경우 미적용

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/skillsets/{skillset-id}/versions/{version}/final-answer' \
--header 'Authorization: Bearer <API-KEY>' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: <X-NCP-CLOVASTUDIO-REQUEST-ID>' \
--header 'Content-Type: application/json' \
--data '{  
    "query": "내일 날씨는 어때?",
    "tokenStream": true,
    "chatHistory": [
        {
            "role": "user",
            "content": "오늘 서울 날씨 어때?"
         },
        {
            "role": "assistant",
            "content": "폭풍전야입니다."
         }
     ],
     "requestOverride": {
        "baseOperation": {
            "query": {
                "appid": "appid-11223344"
                }
            }
        }
    }'

응답

응답 형식을 설명합니다.

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

헤더	필수 여부	설명
Content-Type	-	응답 데이터의 형식 `application/json`

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태
`result`	Object	-	응답 결과
`result.finalAnswer`	String	-	모델의 최종 실행 결과 마지막까지 실행되지 않으면 빈 문자열 반환
`result.tokenCount`	Integer	-	답변 생성 시 측정된 토큰 수
`result.useTask`	Boolean	-	호출한 모델의 학습 여부 `false` \| `true` `false`: 학습하지 않음 `true`: 학습 완료
`result.apiResult`	Array	-	호출한 API 결과

apiResult

apiResult에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`url`	String	-	답변 과정에서 호출한 API URL
`requestBody`	String	-	답변 과정에서 호출한 API 요청 바디
`responseBody`	String	-	답변 과정에서 호출한 API 응답 바디
`apiOrder`	Integer	-	API 호출 결과에 상관없이 응답 순서를 고정하기 위한 정렬 기준
`operationId`	String	-	답변 과정에서 호출한 API Spec의 오퍼레이션 아이디
`nameForHuman`	String	-	답변 과정에서 호출한 API가 등록된 스킬의 이름

응답 예시

응답 예시는 다음과 같습니다.

성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

{
  "status": {
    "code": "20000",
    "message": "OK"
  },
  "result": {
    "finalAnswer": "내일 서울 날씨는 맑음이며, 온도는 약 27도 정도로 예상됩니다.",
    "tokenCount": 1032,
    "apiResult": [
      {
        "url": "http://example.com?numOfRows=1&location=서울&date=20240530",
        "requestBody": "string",
        "responseBody": "string",
        "apiOrder": 1,
        "operationId": "weatherAPI",
        "nameForHuman": "WeatherSkill"
      }
    ]
  }
}

실패

호출이 실패한 경우의 구문 예시는 다음과 같습니다.

응답 스트림

생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다.

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

필드	필수 여부	설명
Accept	-	응답 데이터의 형식 `text/event-stream`

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수여부	설명
`selectedSkill`	Object	-	선택된 스킬 이름 Planning event에서만 표시
`finalAnswer`	String	-	모델의 최종 실행 결과 마지막까지 실행되지 않으면 빈 문자열 반환 FinalAnswer event에서만 표시
`tokenCount`	Integer	-	이벤트에서 사용된 토큰 수
`apiResult`	Object	-	답변 과정에서 호출한 API 결과 FinalAnswer event에서만 표시
`apiResult.url`	String	-	답변 과정에서 호출한 API URL
`apiResult.requestBody`	String	-	답변 과정에서 호출한 API 요청 바디
`apiResult.responseBody`	String	-	답변 과정에서 호출한 API 응답 바디
`apiResult.apiOrder`	Integer	-	API 호출 결과에 상관없이 응답 순서를 고정하기 위한 정렬 기준
`apiResult.operationId`	String	-	답변 과정에서 호출한 API Spec의 오퍼레이션 아이디
`apiResult.nameForHuman`	String	-	답변 과정에서 호출한 API가 등록된 스킬의 이름

Token Event

TokenEvent에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`probs`	Array	-	응답 후보 토큰의 목록 및 각 토큰의 확률값
`stopReason`	String	-	결괏값 생성 중단의 이유(일반적으로 마지막 이벤트에 전달) `length` \| `end_token` \| `stop_before` `length`: 길이 제한 `end_token`: 토큰 수 제한 `stop_before`: 답변 생성 중 `stopBefore` 설정값 출현
`text`	String	-	완전한 텍스트 페어

응답 예시

응답 예시는 다음과 같습니다.

성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: planning
data: {"selectedSkill": {["nameForHuman":"호텔 검색"]}, "tokenCount": 432}
id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: cot
data: {"apiResult": [{"url": "https://example.com/search_reviews_get?keyword=지하철역 접근성 좋은", "requestBody": "keyword=지하철역 접근성 좋은", "responseBody": "[{\"review_id\": 5,
\"review_date\": \"20230809\", \"reviewer\": \"ClaudeCalder\", \"rating\": 4.0, \"content\": \"사우나,
수영장 등 부대시설이 없어서 아쉬웠지만 가격이 저렴해서 좋았어요. 근처에 지하철역도 있고 편의점도 있어서 접근성이
좋아요. 잠시 머물기엔 딱 입니다.\", \"hotel_name\": \"Movenpick Hotel\", \"address\": \"서울 광진구
워커힐로 120\", \"room_name\": \"City View\", \"good_cnt\": 9, \"bad_cnt\": 0, \"rating_service\":
3.0, \"rating_clean\": 4.0, \"rating_room\": 4.0}]", "apiOrder": 1}], "tokenCount": 2401 }
id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: finalAnswer
data: {"finalAnswer": "서울에서 지하철역 접근성 좋은 호텔은 Movenpick Hotel이며, 서울 광진구 워커힐로 120에
위치해 있습니다.", "apiResult": [{"url": "https://example.com/search_reviews_get?keyword=지하철역 접근성 좋은", "requestBody": "keyword=지하철역 접근성 좋은", "responseBody":
"[{\"review_id\": 5, \"review_date\": \"20230809\", \"reviewer\": \"ClaudeCalder\", \"rating\": 4.0,
\"content\": \"사우나, 수영장 등 부대시설이 없어서 아쉬웠지만 가격이 저렴해서 좋았어요. 근처에 지하철역도 있고
편의점도 있어서 접근성이 좋아요. 잠시 머물기엔 딱입니다.\", \"hotel_name\": \"Movenpick Hotel\",
\"address\": \"서울 광진구 워커힐로 120\", \"room_name\": \"City View\", \"good_cnt\": 9, \"bad_cnt\":
0, \"rating_service\": 3.0, \"rating_clean\": 4.0, \"rating_room\": 4.0}]", "apiOrder": 1}],
"tokenCount": 214 }
...

실패

호출이 실패한 경우의 구문 예시는 다음과 같습니다.

이 문서가 도움이 되었습니까?

What's Next

CLOVA Studio 문제 해결

요청
응답
응답 스트림

태그