스킬셋 답변 생성
- 인쇄
- PDF
스킬셋 답변 생성
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
Classic/VPC 환경에서 이용 가능합니다.
특정 스킬셋의 API를 호출하여 적절한 답변을 생성합니다.
요청
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.
| 메서드 | URI |
|---|---|
| POST | /v1/skillsets/{skillset-id}/versions/{version}/final-answer |
요청 헤더
헤더에 대한 설명은 다음과 같습니다.
| 헤더 | 필수 여부 | 설명 |
|---|---|---|
| X-NCP-CLOVASTUDIO-API-KEY | Y | 테스트 앱이나 서비스 앱 생성 시 발급받은 API Key |
| X-NCP-CLOVASTUDIO-REQUEST-ID | N | 각 요청에 대한 요청 아이디 |
| Content-Type | Y | application/json |
| Accept | N | text/event-stream |
참고
응답 결과는 기본적으로 JSON 형태로 반환되지만, Accept를 text/event-stream으로 지정 시 응답 결과를 스트림 형태로 반환합니다.
요청 경로 파라미터
파라미터에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| skillset-id | string | Y | 답변 생성 대상 스킬셋 아이디 |
| version | integer / string | Y | 답변 대상 스킬셋의 버전 |
참고
version은 입력할 스킬셋 버전에 따라 integer 와 string 중에 선택하여 요청해 주십시오.
요청 바디
바디의 각 필드에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| query | string | Y | 질의 내용 |
| chatHistory | array | N | 답변 생성 이력 |
| chatHistory.role | enum | Y | 대화 메시지의 역할 |
| chatHistory.content | string | Y | 대화 메시지 내용 |
| tokenStream | boolean | N | 답변 생성 시 토큰 스트리밍 사용 여부 |
| requestOverride | object | N | 오퍼레이션에 적용할 호출 옵션 |
| requestOverride.baseOperation | object | N | 모든 오퍼레이션에 적용할 key-value |
| requestOverride.baseOperation.header | object | N | 모든 API에 적용할 요청 헤더 |
| requestOverride.baseOperation.query | object | N | 모든 API에 적용할 요청 쿼리 파라미터 |
| requestOverride.baseOperation.requestBody | object | N | 모든 API에 적용할 요청 바디(Get 메서드 API에는 적용되지 않음) |
| requestOverride.operations | array | N | 특정 오퍼레이션에 적용한 key-value |
| requestOverride.operations.operationId | string | Y | 특정 API의 오퍼레이션 아이디 |
| requestOverride.operations.header | object | N | 특정 API에 적용할 요청 헤더 |
| requestOverride.operations.query | object | N | 특정 API에 적용할 요청 쿼리 파라미터 |
| requestOverride.operations.requestBody | object | N | 특정 API에 적용할 요청 바디(Get 메서드 API에는 적용되지 않음) |
요청 구문
구문 예시는 다음과 같습니다.
curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v1/skillsets/{skillset-id}/versions/{version}/final-answer' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: <X-NCP-CLOVASTUDIO-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(statusSchema) | - | 응답 상태 |
| result | object | - | 응답 결과 |
| result.finalAnswer | string | - | 모델의 최종 실행 결과(마지막까지 실행되지 않은 경우, 빈 문자열 반환) |
| result.tokenCount | integer | - | 답변 생성 시 측정된 토큰 수 |
| result.useTask | boolean | - | 호출한 모델의 학습 여부 |
| result.apiResult | object | - | 호출한 API 결과 |
| result.apiResult.url | string | - | 답변 과정에서 호출한 API URL |
| result.apiResult.requestBody | string | - | 답변 과정에서 호출한 API 요청 바디 |
| result.apiResult.responseBody | string | - | 답변 과정에서 호출한 API 응답 바디 |
| result.apiResult.apiOrder | integer | - | API 호출 결과에 상관없이 응답 순서를 고정하기 위한 정렬 기준 값 |
| result.apiResult.operationId | string | - | 답변 과정에서 호출한 API Spec의 Operation Id |
| result.apiResult.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의 Operation Id |
| apiResult.nameForHuman | string | - | 답변 과정에서 호출한 API 가 등록된 스킬의 이름 |
Token Event
토큰 스트리밍을 사용하는 경우 Token Data에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| probs | array | - | 응답 토큰의 후보 토큰 및 후보 토큰의 확률값 |
| stopReason | string | - | 토큰 생성 중단 이유 (일반적으로 마지막 이벤트에 전달) |
| 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 }
...
실패
호출이 실패한 경우의 구문 예시는 다음과 같습니다.
참고
버전 관리 기능이 추가되기 전 스킬셋 답변 생성 API의 URI는 /v1/skillsets/{skillset-id}/final-answer입니다. 만약 이 API를 사용하려는 경우, 요청을 위해 필요한 헤더와 경로 파라미터, 바디는 위 본문 내용을 참고해 주십시오.
이 문서가 도움이 되었습니까?