Set Up Custom API

Overview

외부 API를 Target Model/Agent로 등록하여 Datumo Eval에서 모델 평가 및 응답 자동 수집을 수행할 수 있습니다.

핵심 절차는 다음 두 단계입니다.

1. API 호출 동작 구성
2. API 응답(JSON)에서 모델 최종 답변 위치 매핑

Workflow 요약

1. Custom API 등록
2. Request Body에 user_message 전달
3. 실제 API 호출 테스트
4. 응답 JSON에서 최종 답변 위치(JSONPath) 매핑
5. 저장 및 평가에서 사용

아래 섹션에서 순차적으로 안내합니다.

---

Custom API 생성

1. Custom API 생성 시작

① Model/Agent 생성

Model/Agent Management 화면에서 [+ New Model/Agent] 버튼을 선택합니다.

② [Set Up Custom API] 선택하여 등록 시작

두 가지 옵션 중 Set Up Custom API를 선택하여 커스텀 API 등록을 시작합니다.

---

2. 기본 정보 입력

① Model/Agent Role 선택

Custom API는 Target Model/Agent 역할로만 등록할 수 있습니다.

Target Model/Agent 기능을 정상적으로 활용하려면
API Response Mapping에서 모델의 최종 응답 위치를 지정해두는 것을 권장합니다.

② 모델 이름·설명 입력

간단한 설명과 함께 이름을 지정합니다.

---

3. API 요청 구성

3-1. API Request 설정

구성 순서: URL → Method → Header → Parameter → Body

① api url입력

연동할 외부 API의 엔드포인트 URL을 입력합니다.

② HTTP Method를 선택합니다.

• 지원 Method: GET, POST, PUT, DELETE

③ Header/Parameter: 인증 정보 등 필요 값 입력

API 호출에 필요한 인증 값 또는 고정 파라미터를 입력합니다.

• 예: Authorization, model, api-key 등
• [+ Add Key/Value] 버튼을 통해 여러 개의 Header/Parameter를 추가할 수 있습니다.

각 항목은 Request Header 또는 Query Parameter로 활용됩니다.

④ *Request Body 작성

Request Body에는 Datumo Eval에서 전달하는 값(예: user_message)을 포함하여,
API가 기대하는 JSON 구조를 정의합니다.

• 예시

  {
  "model": "your-model",
  "messages": [
  { "role": "user", "content": "`{{user_message}}`" }
  ]
  }

Custom API는 멀티턴 미지원. Interactive Eval에서는 마지막 user 메시지만 API로 전달

Request Body 작성 팁

OpenAI 호환 형식을 사용하면 Role(system, user, assistant)을 명시적으로 구성할 수 있어,
Prompt 설계 및 모델 전환 시에 유리합니다.

system_message, context 등 추가 변수가 필요한 경우,
Custom Parameter를 정의하여 {{system_message}} 형태로 삽입할 수 있습니다.

---

3-2. Custom Parameter 구성

Custom Parameter는 Request Body, Header, Query Parameter 등에 재사용하기 위한 변수입니다.

① 파라미터 정의 예시

• api_key → Header Authorization에 사용
• user_message → Request body 메시지에 삽입
• system_message → 시스템 메시지에 삽입

② 문자열 처리 옵션

Parameter가 빈값으로만 들어가는 경우가 있다면 문자열로 강제 처리해야 할 수 있습니다. 필요 시 Request Body에 parameter를 " "형태로 직접 감싸거나
Custom Parameeter를 입력화면에서 “Process this parameter as string value” 옵션을 선택하면 문자열로 처리합니다.

---

3-3. API 응답 테스트(권장)

입력한 API 설정이 정상 동작하는지 확인하기 위해 실제 요청을 보내 미리 응답을 확인할 수 있습니다.

• [Get Response] 버튼으로 실제 요청 실행
• 오류 발생 시, JSON 유효성, Placeholder 누락 확인

이 단계에서 응답 구조를 확인해 두면, 이후 Response Mapping 설정 시 편리합니다.

---

4. API Response Mapping (권장)

Custom API를 등록할 때, 외부 API의 응답(Response)에서 필요한 데이터를 추출하는 방법을 정의해야 합니다.
API Response Mapping은 Datumo Eval이 응답(JSON)에서 필요한 값을 찾을 수 있도록
모델 답변과 관련 정보를 추출 위치로 지정하는 설정입니다.

Datumo Eval이 Custom API 응답 JSON에서 아래 3개 값을 읽도록 설정합니다.

• 모델 최종 답변(response)
• Retrieved Context(검색·문서 기반 응답 시 사용)
• 응답 메타데이터(responseMetadata)

---

4-1. 매핑 필드 response

1. response : LLM의 최종 응답 텍스트를 추출하는 경로입니다.

예시1. OpenAI 호환 API

• API응답

  {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "안녕하세요! 무엇을 도와드릴까요?"
        }
      }
    ]
  }

• 매핑 경로: response_1.choices[0].message.content
• 추출 결과: "안녕하세요! 무엇을 도와드릴까요?"

예시2. 단순 구조

• API응답

    {
      "data": {
        "answer": "서울의 날씨는 맑습니다."
      }
    }

• 매핑경로: response_1.data.answer

• 추출결과: "서울의 날씨는 맑습니다."

예시3. 배열의 마지막 요소

• API응답

{
  "messages": [
    { "role": "user", "content": "안녕" },
    { "role": "assistant", "content": "안녕하세요!" }
  ]
}

• 매핑 경로: response_1.messages[-1].content
• 추출 결과: "안녕하세요!"
  • [-1]은 배열의 마지막 요소를 의미합니다.

4-2. 매핑 필드 retrievedContexts

예시1. 문서 배열 추출

• 응답

  {
    "answer": "Python은 프로그래밍 언어입니다.",
    "sources": [
      { "title": "Python 소개", "content": "Python은 1991년에 만들어진 언어입니다." },
      { "title": "Python 특징", "content": "Python은 읽기 쉬운 문법을 가지고 있습니다." }
    ]
  }

• 매핑 경로: response_1.sources[*].content
• 추출 결과

  [
    "Python은 1991년에 만들어진 언어입니다.",
    "Python은 읽기 쉬운 문법을 가지고 있습니다."
  ]

예시2. 중첩된 검색 결과

• 응답

  {
    "result": {
      "documents": [
        { "id": 1, "text": "첫 번째 문서 내용" },
        { "id": 2, "text": "두 번째 문서 내용" }
      ]
    }
  }

• 매핑 경로: response_1.result.documents[*].text
• 추출 결과

  [
    "첫 번째 문서 내용",
    "두 번째 문서 내용"
  ]

예시3. 템플릿 문자열로 포맷팅

단순히 값을 추출하는 것 외에도, 템플릿 문자열을 사용하여 원하는 형식으로 컨텍스트를 구성할 수 있습니다.

• 응답

  {
    "search_results": [
      { "doc_id": "DOC001", "title": "Python 기초", "content": "Python은 배우기 쉬운 언어입니다." },
      { "doc_id": "DOC002", "title": "Python 활용", "content": "Python은 데이터 분석에 많이 사용됩니다." }
    ]
  }

• 매핑 경로: 문서(텍스트 직접입력도 가능): {{response_1.search_results[*].content}}
• 추출 결과

  [
    "문서: Python은 배우기 쉬운 언어입니다.",
    "문서: Python은 데이터 분석에 많이 사용됩니다."
  ]

4-3. 매핑 필드 responseMetadata

응답에 포함된 추가 메타데이터를 key-value 형태로 저장합니다.

예시1. 간단한 예시

• 응답

  {
    "answer": "답변입니다.",
    "model": "gpt-4",
    "processing_time": 1.23,
    "session_id": "abc-123"
  }

• 매핑 설정

  
  

• 추출 결과

  {
    "model_name": "gpt-4",
    "latency": 1.23,
    "session": "abc-123"
  }

---

5. 저장 및 사용

① 저장

모든 설정이 끝나면 [Save]를 클릭하여 Custom API를 저장합니다.

② 데이터셋 평가에 사용

Target Model/Agent로 설정된 Custom API는 다음과 같은 곳에서 선택할 수 있습니다.

• Query Set 기반 응답 패칭 실행 (dataset/response-set 생성)

---