SimSimi Workshop
Document
Pricing
Case
Support
Sign In

일상대화 API

심심이챗봇공방(SimSimi Workshop Services, SWS)은 전세계 약 3억 5천만 사용자들에게 즐거움을 제공해 온 일상대화챗봇 '심심이'를 바탕으로 서비스를 제공합니다. '심심이'가 꾸준히 성공적으로 서비스를 해 올 수 있었던 이유는, 세계 각지에서 다양한 배경을 가진 2천 2백만 명 이상의 패널들이 각자의 재치와 영감을 담아 만들어 온 생동감 넘치는 1억 건 이상의 일상대화 전용 대화세트들에 있습니다. 일상대화 API는 이 대화세트들과 심심이팀의 대화처리엔진 AICR를 활용해서 당신의 챗봇이 사용자들에게 웃음과 힐링을 제공할 수 있도록 돕습니다.

작동원리

각 대화세트(talkset)는 질문문장(qtext)과 답변문장(atext)의 쌍으로 이루어집니다.

대화세트 개념도

심심이 대화처리엔진(AICR)은 수많은 대화세트들이 쌓여 있는 대화세트 저장소에서 적절한 응답을 찾는 작업을 합니다. 일상대화 API를 통해 요청이 접수되면 AICR은 대화세트 저장소에서 사용자문장(utext)과 유사도 등의 관련성이 높은 질문문장(qtext)들을 찾아서 후보군을 만들고, 요청에 포함된 파라미터들과 다른 조건들을 고려하여 가장 적절한 하나의 대화세트를 선택합니다.

일상대화 API가 제공하는 답변문장(atext)은 이 과정에서 선택된 대화세트의 답변문장(atext)입니다. 예를 들어 요청의 utext가 "밥은 먹었어?"일 때 일상대화 API는 다음과 같은 과정을 거쳐 atext로 "응 먹었어"를 반환합니다.

일상대화 API 개념도

기본요청

일상대화 API 엔드포인트(https://wsapi.simsimi.com/{VERSION}/talk)를 향해 프로젝트키, 필수파라미터 2개(사용자문장 utext, 언어코드 lang)를 명시하여 POST 요청하면 응답을 받을 수 있습니다.

요청예시

curl -X POST https://wsapi.simsimi.com/190410/talk \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "utext": "안녕", 
            "lang": "ko" 
     }'                     

응답예시

{
  "status":200,
  "statusMessage":"Ok",
  "atext":"뭐이눔아",
  "lang":"ko",
  "request":{
    "utext":"안녕",
    "lang":"ko"
    }
}    
  • atext : 답변문장
  • request : 요청 본문
  • status, statusMessage : 상태정보 (상태코드표 참조)

 

응답제어

각 챗봇의 성격에 맞는 응답을 제공하기 위해 응답을 조절하기 위한 옵션들을 제공합니다.

요청예시

대한민국 또는 미국에서 생성된 대화세트 중에서 나쁜말확률 70% 이하인 문장만을 답변으로 제공받고자 하는 경우 다음과 같이 country, atext_bad_prob_max 두 개의 옵션을 추가해서 요청하면 됩니다.

curl -X POST https://wsapi.simsimi.com/190410/talk \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "utext":"안녕",
            "lang": "ko",
            "country" : ["KR", "US"],
            "atext_bad_prob_max": 0.7
     }'  

응답제어 옵션

  • country : 대화세트 생성국가 필터. 영어, 스페인어와 같이 여러 국가에서 사용되는 언어에서 특정 국가(들)에서 생성한 대화세트들로 응답후보를 한정할 수 있습니다. (ISO-3166-1 alpha-2 국가코드를 10개까지 열거할 수 있음, 미지정시 모든 국가를 대상으로 함.)

  • atext_bad_prob_max, qtext_bad_prob_max, talkset_bad_prob_max : 문장의 나쁜말확률 최댓값. 챗봇의 대답에서 나쁜말을 억제하는 용도로 사용합니다. 많은 경우 응답문장 나쁜말확률 최댓값(atext_bad_prob_max)을 적절히 조절하면 충분하며, 질문문장과 대화세트의 나쁜말확률(qtext_bad_prob_max, talkset_bad_prob_max)을 추가로 지정해서 더 보수적으로 제어할 수 있습니다. 대화세트의 나쁜말확률은 질문문장과 답변문장을 합쳐서 하나의 문장으로 보고 판별합니다. 소숫점 1자리의 확률값 (0.0 ~ 1.0, 미지정시 기본값 0.0)

  • atext_bad_prob_min : 응답문장의 나쁜말확률 최솟값. 챗봇이 나쁜말을 주로 하도록 할 때 사용할 수 있는 옵션입니다. 상당수 챗봇 플랫폼들은 컨텐츠의 건전성과 관련된 제한이 있으니 사용에 유의하시기 바랍니다. 소숫점 1자리의 확률값 (0.0 ~ 1.0, 미지정시 기본값 0.0)

  • atext_length_max, atext_length_min : 응답문장의 길이 범위 지정. 챗봇의 성격이나 대화 상황에 따라서 응답문장의 길이 범위를 정할 수 있습니다.(1 ~ 256의 정수, 미지정시 기본값 atext_length_max은 256, atext_length_min은 1 )

  • regist_date_max, regist_date_min : 대화세트(talkset) 등록일 범위 지정. 최신 트랜드에 민감한 챗봇, 과거에 머물러 있는 챗봇 등을 구현하기 위해 사용할 수 있습니다.(yyyy-MM-dd HH:mm:ss 형식으로 사용, 미지정시 기본값 regist_date_max는 현재시간, regist_date_min은 최초의 대화세트 등록일)  

  • ko_polite_converter : 한국어 응답을 존댓말로 전환. 챗봇이 반말로 하는 응답을 존댓말로 전환해 줍니다. langko인 경우에만 사용 가능합니다. (true|false, 미지정시 기본값 false)

  • suppress_ko_person_name : 한국어 응답에서 사람의 이름 노출 제어. 챗봇의 응답에서 한국어권 사람의 이름이 나타나는 것을 막을 수 있습니다. langko인 경우에만 사용 가능합니다. (R: 일반적인 이름을 대부분 걸러냅니다.)

가르치기 API 연계 옵션

  • teach_api_key : 연계하여 사용하고 싶은 가르치기 API 프로젝트의 API 키를 입력하시면 가르친 대화세트를 우선적으로 대답합니다. utext와 관련하여 가르친 대화세트가 없다면 파라미터를 넣지 않은 경우와 똑같은 결과가 나옵니다. 가르친 대답세트가 나오는 경우 다른 응답제어, 추가정보 파라미터들과 연동되지 않습니다.

  • teach_key : 가르치기 API를 사용했을 때 입력한 teach_key에 해당하는 대화세트들만 대답하게 할 수 있습니다. teach_key와 상관없이 대답이 나오길 바라는 경우 입력하지 않아도 무방합니다. 가르친 대화세트 중 입력한 teach_key에 해당하는 것이 없다면 teach_api_key 파라미터를 넣지 않은 경우와 똑같은 결과가 나옵니다.

 

추가정보

일상대화 API는 응답에 대한 자세한 정보를 얻을 수 있는 방법을 제공합니다. 요청 본문의 cf_info 오브젝트에 제공받고자 하는 추가정보들을 예시와 같이 열거하여 요청합니다.

요청예시

curl -X POST https://wsapi.simsimi.com/190410/talk \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "utext":"안녕",
            "lang": "ko",
            "cf_info" : [
                  "qtext",
                  "country",
                  "atext_bad_prob",
                  "atext_bad_type",
                  "regist_date"
            ],
     }'         

응답예시

{
    "status" : 200,
    "statusMessage" : "OK",
    "atext" : "안녕 오늘날씨 참 좋지?",
    "lang" : "ko",
    "utext" : "안녕",
    "qtext" : "안녕~~",
    "country" : "KR",
    "atext_bad_prob" : 0.0,
    "atext_bad_type" : "dpd",
    "regist_date" : "2017-07-08 08:24:37"
}                           
  
  

추가정보 요청 옵션

  • qtext : 답변문장(atext)과 쌍인 질문문장(qtext)
  • country : 대화세트 생성 국가의 국가코드(ISO-3166-1 alpha-2)
  • atext_bad_prob : 답변문장(atext)의 나쁜말 확률
  • atext_bad_type : 답변문장의 나쁜말 확률(atext_bad_prob) 추정 시 사용한 판별 방식. STAPX, DPD, WPF, HB10A 중 하나. (판별방식에 대한 자세한 설명 )
  • regist_date : 대화세트 생성 시점

 

일상대화 지원언어

대부분의 언어코드는 ISO-639-1과 동일하지만, 다른 사례(*)가 있으니 주의하세요.

언어명언어명(네이티브)언어코드
갈리시아어Galegogl
구자라트어ગુજરાતીgu
그루지야어ქართულიka
그리스어Ελληνικάel
네덜란드어Nederlandsnl
네팔어नेपालीne
노르웨이어(보크몰)Norsknb
덴마크어Danskda
독일어Deutschde
라트비아어Latviešulv
러시아어русскийru
루마니아어Românăro
리투아니아어Lietuviųlt
마라티어मराठीmr
마케도니아어македонскиmk
말라얄람어മലയാളംml
말레이어Melayums
몽골어Монголmn
바스크어Euskaraeu
버마어မြန်မာဘာသာmy
베트남어Tiếng Việtvn*
벨로루시어беларускаяbe
벵골어বাংলাbn
보스니아어Bosanskibs
불가리아어българскиbg
세르비아어српскиrs*
세부아노Cebuanocx*
스와힐리어Kiswahilisw
스웨덴어Svenskasv
스페인어Españoles
슬로바키아어Slovenčinask
슬로베니아어Slovenščinasl
신할라어සිංහලsi
아랍어العربيةar
아르메니아어հայերենhy
아이슬란드어íslenskais
아제르바이잔어Azərbaycancaaz
아프리칸스어Afrikaansaf
알바니아어Shqipal*
에스토니아어Eestiet
영어Englishen
우르두어Урдуur
우즈베크어O‘zbekuz
우크라이나어українськаuk
웨일즈어Cymraegcy
이탈리아어Italianoit
인도네시아어Bahasa Indonesiaid
일본어日本語ja
중국어中文ch*
체코어češtinacs
카자흐어қазақkk
카탈로니아어Catalàca
칸나다어ಕನ್ನಡkn
캄보디아어ភាសាខ្មែរkh*
쿠르드어Kurdî (Kurmancî)ku
크로아티아어Hrvatskihr
타갈로그어Filipinoph*
타밀어தமிழ்ta
타직어Тоҷикӣtg
태국어ภาษาไทยth
터키어Türkçetr
텔루구어తెలుగుte
파슈토어پښتوps
펀자브어ਪੰਜਾਬੀpa
페르시아어فارسیfa
포르투갈어Portuguêspt
폴란드어Polskipl
프랑스어Françaisfr
프리지아어Fryskfy
핀란드어Suomifi
한국어한국어ko
헝가리어Magyarhu
히브리어עבריתhe
힌디어हिन्दीhi
아삼어অসমীয়াas
브르타뉴어Brezhonegbr
과라니어Guaranign
자바어Basa Jawajv
오리야어ଓଡ଼ିଆor
키냐르완다어Ikinyarwandarw
중국어 (번체)繁體中文zh*

 

일상대화 상태코드표

statusstatusMessage설명
200OK정상
227Parameter Required필수 파라미터 누락
228Do Not Understand질문에 대한 답변을 찾을 수 없음
403Unauthorized유효하지 않은 API Key
429Limit Exceeded사용 한도 초과
500Server error서버 오류

 

나쁜말확률

나쁜말확률은 불건전한(또는 악성) 문장을 구별하기 위해 심심이팀이 개발한 지표입니다. 뛰어난 성능을 보이는 고급 딥러닝 기술을 포함해 다양한 기법을 동원하여 산출합니다. 자세한 내용은 다음 블로그 포스트를 참고하시기 바랍니다. (심심이 대화 품질 - 나쁜말 필터 관련 기술)

 

 

 

나쁜말점수 API

세계 최고 성능의 대화체 문장 분류 기술로 게임 내 채팅, 실시간 방송 채팅, 게시판 덧글, 다국어 커뮤니케이션 등에서 욕설이나 선정적인 문장을 정확하고 유연하게 판별해 낼 수 있습니다. 전통적인 단어와 문구 필터 방식(WPF)에서도 다양한 옵션을 제공하며 통계 기반의 확률적 유사성 기반 분류 기법(STAPX)은 가장 많은 언어를 커버합니다. 심층신경망 모델 기반 문장 분류 기법(DPD)은 99.3% 이상의 F1 Score를 기록하였으며(한국어 기준) 크라우드소싱으로 10명의 패널이 검증하는 최상위 신뢰도의 분류 기법(HB10A)까지 활용할 수 있습니다.

 

판별 범위와 점수 기준

  • 심심이 컨텐츠 금지 규정에 해당하는 문장에 높은 점수가 부여됩니다.
    심심이 컨텐츠 금지 규정

  • 주로 '채팅에 사용되는 대화체 문장'에서, '문장 자체가 직접적으로 나쁜말(판별기준 참고)에 해당하는 표현'을 판별합니다. 이전 대화의 맥락, 상대방의 대화와 조응하여 형성되는 의미 및 중의적 표현은 판별 범위에서 제외됩니다.

 

요청

나쁜말 판별기 API 엔드포인트(https://wsapi.simsimi.com/{VERSION}/classify/bad)를 향해 프로젝트키, 필수파라미터 3개(문장 sentence, 언어코드 lang, 타입 type)를 명시하여 POST 요청하면 응답을 받을 수 있습니다.

요청예시

curl -X POST https://wsapi.simsimi.com/190410/classify/bad \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "sentence": "시발", 
            "lang": "ko",
            "type": "DPD"
     }'                     

응답예시

{
  "status":200,
  "statusMessage":"Ok",
  "bad":"0.999993",
  "request":{
    "sentence":"시발",
    "lang":"ko"
    }
}    
  • bad : 문장이 나쁜 말일 확률
  • request : 요청 본문
  • status, statusMessage : 상태정보 (상태코드표 참조)

 

나쁜말점수 지원언어

대부분의 언어코드는 ISO-639-1과 동일하지만, 다른 사례(*)가 있으니 주의하세요.

언어명언어명(네이티브)언어코드F1 Score
말레이어Melayums0.8984
베트남어Tiếng Việtvn*0.9132
아랍어العربيةar0.9432
영어Englishen0.9847
인도네시아어Bahasa Indonesiaid0.9497
터키어Türkçetr0.9502
포르투갈어Portuguêspt0.9836
프랑스어Françaisfr0.9376
한국어한국어ko0.9930

 

나쁜말점수 상태코드표

statusstatusMessage설명
200OK정상
403Unauthorized유효하지 않은 API Key
429Limit Exceeded사용 한도 초과
500Server error서버 오류

 

 

 

가르치기 API

일상대화 API를 사용하면서 가르치기 API로 저장한 대화세트들을 우선적으로 대답하게 할 수 있습니다. 가르치기 API의 기능을 사용하고 싶다면 일상대화 API Standard 버전이 필요합니다.

가르치기 API 개념도01 가르치기 API 개념도02 가르치기 API 개념도03

 

가르치기

가르치기 API 엔드포인트(https://wsapi.simsimi.com/{VERSION}/teach) 를 향해 프로젝트키, 필수파라미터 4개(문장 qtext, 답변 atext, 언어코드 lang, 키 teach_key)를 명시하여 POST 요청하면 해당 프로젝트에 대화세트가 저장됩니다. teach_key 값은 가르치는 대화세트들을 그룹화하는데 사용할 수 있습니다.

요청예시

curl -X POST https://wsapi.simsimi.com/190410/teach \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "qtext": "심심아 안녕",
            "atext": "안녕, 반가워",
            "lang": "ko",
            "teach_key": "example"
     }'                     
  • qtext : 사용자문장
  • atext : 답변문장
  • lang : 사용자의 언어코드
  • teach_key : 대화세트를 분류하는 키값

응답예시

{
  "status":200,
  "statusMessage":"Ok",
  "request":{
    "qtext": "심심아 안녕",
    "atext": "안녕, 반가워",
    "lang": "ko",
    "teach_key": "example"
  }
}    
  • request : 요청 본문
  • status, statusMessage : 상태정보 (상태코드표 참조)

 

일상대화 API와의 연계

프로젝트의 api키와 teacy_key를 사용하여 일상대화 API와 연계가 가능합니다. 가르치기 API로 저장한 대화세트는 일상대화 API에서 우선적으로 사용하실 수 있습니다. 사용 방법은 응답제어를 참조하십시오.

 

관리 페이지

프로젝트 대시보드를 통해 관리페이지로 접근할 수 있습니다. 현재 관리 페이지에서는 가르친 대화세트들의 열람과 삭제가 가능합니다.

 

가르치기 상태코드표

statusstatusMessage설명
200OK정상
403Unauthorized유효하지 않은 API Key
500Server error서버 오류
© SimSimi Inc. 2020
Terms and Conditions
Privacy Policy
Location Information Terms and Conditions
Brand Guideline
English
한국어
English