스킬셋 답변 생성

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"
      }
    ]
  }
}

실패

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

응답 스트림

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