Alli Generative Answer API

Generative Answer API를 사용하면 여러 소스 문서를 바탕으로 LLM 모델이 질문에 대한 답변을 생성할 수 있습니다.

API 키 얻기

각 요청의 헤더에 프로젝트에 할당된 API-KEY 를 제공해야 합니다. API 키는 대시보드의 설정 메뉴 아래 일반 탭에서 찾을 수 있습니다.

에이전트 혹은 유저 정보 입력하기

특정 엔드포인트에는 리퀘스트 헤더에 에이전트나 유저 정보를 이용해 누가 API 콜을 실행하는지 지정할 수 있습니다.

유저 정보는 OWN-USER-ID 에 유저 ID 를 입력하여 제공할 수 있습니다. 기존 유저 ID 를 사용하거나 새로운 ID 를 사용할 수 있으며, 새로운 ID 가 입력되면 Alli 가 해당 ID 로 신규 유저를 생성합니다. 이후 같은 OWN-USER-ID 헤더가 사용되면 해당 콜은 동일 유저가 실행한 것으로 인식됩니다. OWN-USER-ID (optional): 프로젝트에서 사용할 User ID (User ID별로 session 이 관리됩니다.) 기존에 존재하지 않는 User ID 를 사용할 시, 새로운 User 가 생성됩니다. OWN-USER-ID를 입력하지 않을 시 프로젝트 별 기본 USER ID가 사용이 되며, threadId 기능을 사용할 수 없게 됩니다.

또한 유저 ID 를 사용할 때 유저의 이메일 정보를 업데이트할 수 있습니다. USER-EMAIL 헤더에 업데이트를 원하는 이메일을 입력하면 됩니다. 아래는 입력 예시입니다.

-H 'OWN-USER-ID: 5f1234567a409876c082487z' \

-H 'AGENT-EMAIL: [e-mail]'

OWN-USER-ID 에는 ASCII 캐릭터만 사용할 수 있습니다. 사용하고자 하는 유저 ID 에 ASCII 캐릭터가 아닌 캐릭터가 포함되는 경우, base64 인코딩 후 base64:CONVERTED_ID 형식을 사용할 수 있습니다.

유저 ID 정보는 Alli 대시보드의 고객 메뉴에서 확인할 수 있습니다.

에러 메시지

예상했던 response 를 받지 못한 경우 에러 메시지를 확인해 주세요. 예를 들어 잘못된 HTTP 메소드를 사용한 경우 아래와 같은 형식의 에러 메시지가 리턴됩니다.

{“errors”: “Method Not Allowed PUT: /webapi/generative_answer”}

답변 생성

POST https://backend.alli.ai/webapi/generative_answer

Generative Answer API는 비정형 텍스트 문서, Q&A 및 복잡한 테이블에서도 답변을 생성할 수 있습니다.

Headers

Name	Type	Description
API-KEY(required)*	string	할당된 API 키입니다. 대시보드의 설정 메뉴 > 일반 탭에서 찾을 수 있습니다.
OWN-USER-ID(optional)	string	프로젝트에서 사용할 User ID (User ID별로 session 이 관리됩니다.) 기존에 존재하지 않는 User ID 를 사용할 시, 새로운 User 가 생성됩니다. OWN-USER-ID를 입력하지 않을 시 프로젝트 별 기본 USER ID가 사용이 되며, threadId 기능을 사용할 수 없게 됩니다.

Request Body

Name	Type	Description
query(required)	string	문자열 형식의 검색 쿼리입니다.
model(required)	string	답변을 생성할 LLM을 선택할 수 있습니다. 기본 모델은 GPT 3.5 Turbo입니다. 사용 가능한 모델 옵션은 하기 표를 참조해 주세요.
answer_format	string	DRAFTJS 혹은 MARKDOWN입니다. 기본값은 DRAFTJS입니다.
ThreadId	string(UUID)	threadId는 Stateful = True 일 때 사용됩니다. 처음 대화를 시작할 때는 공백이며 그 다음 쿼리부터는 출력의 threadId를 사용합니다. 처음 대화부터 threadId를 설정하고 싶은 경우에는 UUID 형식으로 작성할 필요가 있습니다. 예시 UUID - 36e7bb2b-1063-47ec- (Default = None)
isStateful	Boolean	후속 질문을 사용하기 위해서는 이전 대화 이력이 필요합니다. 대화 이력은 threadId를 통해 관리됩니다. isStateful option을 True로 설정하고threadId를 입력하면 이전 대화 이력을 바탕으로 쿼리가 재작성됩니다. (Default = False)
promptGroupId(required)	String	답변 생성에 사용되는 프로젝트의 그룹 프롬프트입니다. 해당 설정은 디폴트로 제공된 그룹 프롬프트를 편집해서 사용하는 경우에 유효합니다. Id는 프로젝트 설정 > 프롬프트 관리 > 답변 생성 > 그룹 프롬프트 탭에서 사용 중인 그룹 프롬프트를 선택할 때 표시된 URL을 통해 Id를 확인할 수 있습니다. 예시 링크 : https://app.alli.ai/projects/UHJvamVjdDo2NTwNmI4Y2RkZTJiMzg4OTE=/settings/prompt-management/generative-answer/groups/TEqNUHJvbXA0R3JvdXA6NoU2ZmY2MGZkOGQ7MDU5MjdhNWYwMDBk groups 뒤 빨간 텍스트가 Prompt Group ID입니다.
mode	String	데이터를 Stream 하게 출력할지, Sync 로 출력할지 여부를 결정할 수 있습니다 (Default=sync) Stream 모드일 경우, Sync 와 동일한 out format 의 json string 을 streaming 하게 출력합니다.
hashtags	json	search_from 의 값 중 qna, document 카테고리의 hashtag를 지정하는 데 사용됩니다. 예) "hashtags" : { "qnaInclude" : ["hash name", "hash name2"], "qnaIncludeOption" : "and"/"or", "qnaExclude" : ["hash name", "hash name2"], "qnaExcludeOption" : "and"/"or", "docsInclude" : ["hash name", "hash name2"], "docsIncludeOption" : "and"/"or", "docsExclude" : ["hash name", "hash name2"], "docsExcludeOption" : "and"/"or", }
search_from(required)	json	Generative Answer 에서 데이터를 찾기 위한 소스 데이터의 범위를 지정합니다. 현재 사용 가능한 값은, web, qna, document 와 같으며, list 형태로 데이터를 입력합니다. 예) [“web”, “qna”]

promptGroupId 참조하는 방법

200

You will get the result as the following JSON format:

answer: It's the answer extracted from uploaded documents in the dashboard.answerHash: This is used to identify the answer to give or cancel feedback.

answerHash: This is used to identify the answer to give or cancel feedback.

confidence: It shows the confidence value from AI model. Shown as a number value between 0 and 1.

effectiveConfidence: When you provide feedback to the query result, it automatically trains the AI model. Effective confidence is the adjusted score with these users' and agents' feedback. Shown as a number value between 0 and 1.

documentId: The document's ID where the answer is extracted from.

documentName: The document's name where the answer is extracted from.hashtags: The hashtags attached to the document.

pageNo: The page number in the document where the answer was derived.

createdDate: The date when the document was uploaded.

agentFeedback: The feedback from agents (through dashboard and REST calls) about this document

userFeedback: The feedback from users about this document

body: If returnPreview is true in the request, the html body of the document search preview is displayed.

css: If returnPreview is true in the request, the css of the document search preview is displayed.

pdfPreview: If returnPdfPreview is true in the request, the URL to a PDF preview of the document with the answer highlighted is displayed. Note that the URL can be restricted using the Download IP Allowlist setting.

folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.

editor: List of the agents' email who has the editor access to the documents (if they're set in the Alli dashboard).

viewer: List of the agents' email who has the viewer access to the documents. (if they're set in the Alli dashboard).

The number of search results and the threshold follows your dashboard setting. Please check your setting in Documents > Settings.

사용 가능한 LLM Models

OPENAI GPT3.5 TURBO "turbo"
OPENAI GPT3.5 TURBO 16K "turbo_16k"
OPENAI GPT3.5 TURBO INSTRUCT "turbo_instruct"
OPENAI GPT4 "gpt4"
OPENAI GPT4 TURBO "gpt4_turbo"
OPENAI GPT4 TURBO VISION "gpt4_turbo_vision"
OPENAI GPT4 32K "gpt4_32k"
AZURE GPT3.5 TURBO "azure_turbo"
AZURE GPT3.5 TURBO 16K "azure_turbo_16k"
AZURE GPT3.5 TURBO JA "azure_turbo_ja"
AZURE GPT4 "azure_gpt4"
AZURE GPT4 TURBO "azure_gpt4_turbo"
OPENAI GPT-4o "gpt4_o"
OPENAI GPT-4o mini "gpt4_o_mini"
GOOGLE PALM2 "vertex_text_bison"
NAVER HYPER CLOVA X "hyper_clova_x_lk_0"
ANTHROPIC CLAUDE 2 "anthropic_claude_2"
ANTHROPIC CLAUDE 3 OPUS "anthropic_claude_3_opus"
ANTHROPIC CLAUDE 3 HAIKU "anthropic_claude_3_haiku"
GEMINI PRO "gemini_pro"
GEMINI PRO VISION "gemini_pro_vision”
ALPHA F V2 EEVE "alpha_f_v2_eeve"

Output

answer : Generative Answer 의 실행결과 생성된 답변.

intent : Generative Answer 의 intent (SEARCH, END_OF_CONVERSATION 둘 중 하나) 

clues(list) : (PARAMETER 의 clues 가 True 일때만) answer를 생성할 때 사용된 clue 리스트.

clueId : Alli 에서 관리되는 clue의 unique id.

source : clue 의 type(DOCUMENT, FAQ).

title : Alli 에 저장된 document, faq 의 title.

pageNo : (type이 document 일때만) document 의 page number. 

kbId : (type 이 document 일때만) Alli에서 관리되는, document 의 unique id.

faqId : (type 이 faq 일때만) Alli에서 관리되는, faq 의 unique id.

text : (type 이 document 이고, clueText가 true 일때만) clue로 사용된 document의 text

threadId : (PARAMTER 의 is_stateful이 True 일때만) threadId 가 input 으로 주어지면 해당 값이 그대로 반환, 그렇지 않을 시 신규 thread id 가 생성되어 반환됨.

fuQuestion : (PARAMTER 의 is_stateful이 True 일때만) 동일 threadId 내의 질의와 응답 결과를 사용하여 새로운 쿼리가 생성됐을 경우, 해당 값이 반환됨.

예, 같은 threadId 내에서 직전에 홍길동의 고향은? 이라는 질문이 있었고, 그 다음에 그의 나이는? 이라는 질문을 할 경우, fu_question 은 “홍길동”의 나이는? 과 같이 생성되고, 해당 question 으로 질의

Request Example

YOUR API KEY를 프로젝트의 API 키로 바꾸어야 합니다.

curl -X POST -d '{ 
  "query": "can I disclose the composite ratings?",
  "model": "gpt4",
  "isStateful": "True",
  "threadId": "UUID" }' \
  "promptGroupId": "XXXXXXXXXXXXXXXXXXX", 
-H 'API-KEY: REST_API_KEY' \
-H 'Content-Type: application/json' \
https://backend.alli.ai/webapi/generative_answer

Response Example

{
    "answer": {
        "blocks": [
            {
                "key": "k0",
                "text": "You can disclose the composite ratings to bank management after the examiner-in-charge (EIC) has discussed the recommended component and composite ratings with senior management and, when appropriate, the board of directors near the conclusion of the examination [1]. Generally, in these situations, examiners should contact the regional office overseeing the institution and discuss the proposed ratings with the case manager or assistant regional director prior to disclosing the ratings to management or the board [3].",
                "inlineStyleRanges": [],
                "entityRanges": [
                    {
                        "key": 0,
                        "offset": 263,
                        "length": 3
                    },
                    {
                        "key": 1,
                        "offset": 517,
                        "length": 3
                    }
                ],
                "type": "unstyled"
            }
        ],
        "entityMap": {
            "0": {
                "type": "LINK",
                "mutability": "MUTABLE",
                "data": {
                    "url": YOUR URL ADDRESS
                }
            },
            "1": {
                "type": "LINK",
                "mutability": "MUTABLE",
                "data": {
                    "url": YOUR URL ADDRESS
                }
            }
        }
    },
    "threadId": "UUID", //For the next question, send in the body to remember previous questions.
    "fuQuestion": null
}

Output Example

{
  "answer": "{\"blocks\": [{\"key\": \"k0\", \"text\": \"그의 고향은 문산입니다. [1], [2]\", \"inlineStyleRanges\": [], \"entityRanges\": [{\"key\": 0, \"offset\": 14, \"length\": 3}, {\"key\": 1, \"offset\": 19, \"length\": 3}], \"type\": \"unstyled\"}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"isFromKnowledgeBase\": true, \"source\": \"DOCUMENT\", \"url\": \"http://localhost:8100/projects/UHJvamVjdDo2NTZkOGM5ZTc2Mzg0ODI1NjA0YTEyZTE=/knowledgeBases/S25vd2xlZGdlQmFzZTo2NTZkOGQ1ZGUwZDM0NDQ5NjliNjFkZWQ=/preview?page=1\", \"knowledgeBasePreview\": {\"pageNo\": 1, \"totalPageCount\": 1, \"knowledgeBase\": {\"id\": \"S25vd2xlZGdlQmFzZTo2NTZkOGQ1ZGUwZDM0NDQ5NjliNjFkZWQ=\", \"title\": \"tt2.txt\"}, \"clueId\": \"Q29nbml0aXZlQ2x1ZTo2NTc2NTZkMmI2NGM5ZGE0MzYzYTY0ZjlfMA==\"}}}, \"1\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"isFromKnowledgeBase\": true, \"source\": \"DOCUMENT\", \"url\": \"http://localhost:8100/projects/UHJvamVjdDo2NTZkOGM5ZTc2Mzg0ODI1NjA0YTEyZTE=/knowledgeBases/S25vd2xlZGdlQmFzZTo2NTZlMzlmMWQ4MzMxZmY3ODlkZjdhYjE=/preview?page=1\", \"knowledgeBasePreview\": {\"pageNo\": 1, \"totalPageCount\": 1, \"knowledgeBase\": {\"id\": \"S25vd2xlZGdlQmFzZTo2NTZlMzlmMWQ4MzMxZmY3ODlkZjdhYjE=\", \"title\": \"tt3.txt\"}, \"clueId\": \"Q29nbml0aXZlQ2x1ZTo2NTc2NTZkMmI2NGM5ZGE0MzYzYTY0ZjlfMQ==\"}}}}}",
  "threadId": "ebc480f2-3c93-4dfe-913f-4fabd13f0ab1",
  "fuQuestion": "What is the hometown of the person mentioned?",
  "clues": [
    {
      "clueId": "Q29nbml0aXZlQ2x1ZTo2NTc2NTZkMmI2NGM5ZGE0MzYzYTY0ZjlfMA==",
      "source": "DOCUMENT",
      "title": "tt2.txt",
      "pageNo": 1,
      "kbId": "S25vd2xlZGdlQmFzZTo2NTZkOGQ1ZGUwZDM0NDQ5NjliNjFkZWQ=",
      "faqId": null
    },
    {
      "clueId": "Q29nbml0aXZlQ2x1ZTo2NTc2NTZkMmI2NGM5ZGE0MzYzYTY0ZjlfMQ==",
      "source": "DOCUMENT",
      "title": "tt3.txt",
      "pageNo": 1,
      "kbId": "S25vd2xlZGdlQmFzZTo2NTZlMzlmMWQ4MzMxZmY3ODlkZjdhYjE=",
      "faqId": null
    }
  ]
}