> For the complete documentation index, see [llms.txt](https://docs.datumo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datumo.com/documentation/get-started/undefined/5.-application-api.md).
# 5. Application API 연동
## Application API 연동
생성한 Application의 Module과 Version에 실제 AI 서비스의 API를 연결합니다. 연동이 완료되면 Evaluation, Redteaming, Observability 모듈이 서비스를 직접 호출하여 평가·공격·관찰 작업을 수행할 수 있습니다.
***
### 연동 개요
Application API 연동은 다음 4단계로 진행됩니다. 각 단계는 순차적으로 이어지며, 1단계에서 정의한 Key 구조가 이후 모든 단계의 기준이 됩니다.
1. **Module 세팅:** 평가 대상 모듈의 Input/Output Key를 정의
2. **Version 세팅:** Before-After 비교를 위한 버전 등록
3. **Version별 API 연동:** 각 버전의 실제 API 엔드포인트 연결
4. **API별 Output Key 맵핑:** API 응답을 Output Key에 자동 매핑
## Module
Module은 Application을 구성하는 기능 단위입니다. 평가하고자 하는 세부 기능에 따라 Module Type을 선택하여 설정할 수 있습니다.
**Module Key**
각 Module은 `Input Key`와 `Output Key`를 가집니다.
* `Input Key` : Module에 전달되는 입력값입니다.
* `Output Key` : Module 실행 후 생성되는 출력값입니다.
### 1. Module 생성
`+ New Module` 를 선택합니다.
Module Type을 선택한 다음, `Add` 버튼을 선택합니다. Module Type은 복수 선택할 수 있습니다.
### 2. Module 수정
각 Module 우측 상단에 있는 수정 아이콘을 클릭합니다.
Module의 이름과 Input/Output key를 수정할 수 있습니다.
* `+Add Input Key` 를 선택하면 Input Key를 추가 할 수 있습니다.
* `+Add Output Key` 를 선택하면 Output Key를 추가 할 수 있습니다.
단, Input key나 Output key 중 하나라도 수정 되는 경우, 해당 Application에 속해 있는 모든 버전 세팅을 처음 부터 다시 해야 합니다.
### 3. Module 삭제
`Delete` 버튼을 선택 합니다.
입력창에 "Delete module"을 입력하면 `Delete` 버튼이 활성화 되며, `Delete` 버튼을 선택하면 해당 Module이 삭제 됩니다.
***
## Version
다투모 플랫폼은 하나의 Application을 여러 Version으로 관리할 수 있습니다. 프롬프트 수정, 모델 변경, 검색 로직 개선 등 변경 사항이 있을 때마다 새로운 Version을 등록하면 동일한 평가 기준으로 Before-After를 비교할 수 있습니다.
### 1. Version 생성
#### Version 운영 팁
* **변경 단위로 Version 분리**: 한 번에 여러 가지를 바꾸면 어떤 변경이 점수에 기여했는지 분리할 수 없습니다. 가능한 한 단일 변경 단위로 Version을 나누는 것이 정량 분석의 기본입니다.
* **명명 규칙 통일**: 팀 내에서 Version 이름 규칙을 미리 합의해두면 대시보드에서 시계열 비교가 쉬워집니다.
* **삭제보다 비활성화**: 실패한 Version도 삭제하지 말고 비활성화 상태로 보존하면, 이후 회귀 테스트나 재현 검증이 가능합니다.
### 2. Version별 API 연동
각 Version은 실제로 호출 가능한 AI 서비스 API와 연결되어야 평가·공격·관찰을 실행할 수 있습니다. Version마다 별도의 엔드포인트를 지정할 수 있어, 동일한 평가셋을 여러 환경(스테이징·프로덕션·신규 모델)에 동시에 적용하는 것도 가능합니다.
#### 연동 정보 입력
Version 목록에서 대상 Version의 **API 연동** 영역으로 진입한 뒤, E2E 또는 Module별로 다음 정보를 입력합니다.
**Endpoint 정보**
* **Method**: `GET`, `POST`, `PUT` 중 선택 (대부분의 LLM API는 `POST`)
* **URL**: 호출할 API의 전체 주소
**Header** 인증 토큰, Content-Type 등 요청 헤더를 Key-Value 쌍으로 추가합니다. 민감 정보(API Key, Bearer Token)는 `Secret` 옵션으로 등록하면 마스킹된 상태로 안전하게 저장·전송됩니다.
**Request Body** JSON 형식의 요청 본문 템플릿을 작성합니다. Step 1에서 정의한 **Input Key는 `{{key_name}}` 형식의 변수**로 삽입할 수 있으며, 평가 실행 시 벤치마크셋의 실제 값으로 자동 치환됩니다.
```
{
"model": "gpt-4o",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "{{user_query}}" }
],
"temperature": 0.2
}
```
위 예시에서 `{{user_query}}` 부분은 실행 시점에 벤치마크셋 각 행의 `user_query` 값으로 치환되어 호출됩니다. 변수명은 Step 1에서 정의한 Input Key 이름과 정확히 일치해야 합니다.
#### 연결 테스트
설정을 저장하기 전에 **Test Call** 버튼으로 실제 API가 정상 호출되는지 확인할 수 있습니다. 테스트 입력값을 임의로 채워 넣고 호출하면, 응답 코드(`200 OK` 등)와 Raw Response가 화면에 표시됩니다. 이 단계에서 인증 오류나 본문 형식 오류를 미리 잡아두면 이후 평가 실행 중 발생하는 대량 실패를 크게 줄일 수 있습니다.
***
### 4. API별 Output Key 맵핑
API가 정상적으로 호출되더라도, DATUMO가 응답에서 **어느 값을 평가 대상으로 삼을지**는 별도로 알려주어야 합니다. 이 단계에서는 Step 3의 Test Call로 받은 실제 응답 구조를 기준으로, **Output Key와 응답 JSON의 경로를 1:1로 맵핑**합니다.
#### JSONPath 기반 맵핑
각 Output Key 옆에 응답 JSON의 경로를 [JSONPath](https://goessner.net/articles/JsonPath/) 표기법으로 입력합니다. 예를 들어 OpenAI ChatCompletion API의 응답이 아래와 같다면,
```
{
"id": "chatcmpl-xxx",
"choices": [
{
"message": {
"role": "assistant",
"content": "환불은 마이페이지 > 주문 내역에서 신청할 수 있습니다."
},
"finish_reason": "stop"
}
],
"usage": { "total_tokens": 142 }
}
```
`answer` Output Key는 `$.choices[0].message.content` 경로로 맵핑합니다. RAG 서비스에서 검색 결과를 함께 받는 경우 `retrieved_docs` Output Key는 `$.context.documents`처럼 응답 구조에 맞게 지정하고, 토큰 사용량을 별도 분석하고 싶다면 `$.usage.total_tokens` 경로의 Key를 추가할 수도 있습니다.
#### 맵핑 검증
맵핑을 마친 후 **Preview** 버튼을 누르면 Test Call의 응답에서 각 Output Key가 실제로 어떤 값을 추출하는지 미리 확인할 수 있습니다. 의도한 값이 정확히 추출되는지 반드시 확인한 뒤 저장하세요. 잘못 맵핑된 Key는 모든 평가 결과 전체에 노이즈를 만들 수 있어, 점수 변화의 원인을 추적할 수 없게 됩니다.
#### 누락된 Output Key 처리
API 응답에 특정 Output Key에 해당하는 값이 항상 존재하지 않을 수 있습니다. 예컨대 검색 결과가 없을 때의 `retrieved_docs`, 도구 호출이 없는 턴의 `tool_calls`가 그렇습니다. 이 경우 **기본값(Default Value)** 지정 또는 **Null 허용** 옵션을 설정해 평가 실행이 중단되지 않도록 처리할 수 있습니다.
***
### 연동 완료 후
4단계가 모두 완료되면 해당 Version은 **연동 완료** 상태로 표시되며, 이제 다음 작업이 가능해집니다.
* **Evaluation 모듈에서 평가 실행**: [E-5. Run Eval](https://app.gitbook.com/o/Bis7EnmqiVzacnbqBO3C/s/JTwnb351jHLY7t48GvYX/~/edit/~/changes/DMRf5OO7Z5z4Xpgr0Hqc/evaluation/how-to-work/5.-run-eval)에서 본 Application·Version을 선택해 벤치마크셋 기반 평가를 수행할 수 있습니다.
* **Redteaming 모듈에서 공격 실행**: [R-2. Auto Redteaming 실행](https://app.gitbook.com/o/Bis7EnmqiVzacnbqBO3C/s/JTwnb351jHLY7t48GvYX/~/edit/~/changes/48/redteaming/how-to-work/2.-auto-redteaming)에서 본 Application을 대상으로 적대적 시나리오 공격을 자동 생성·실행할 수 있습니다.
* **Observability 모듈에서 실유저 대화 수집**: [O-2. Scenario Setting](https://app.gitbook.com/o/Bis7EnmqiVzacnbqBO3C/s/JTwnb351jHLY7t48GvYX/~/edit/~/changes/48/observability/how-to-work/2.-scenario-setting)에서 본 Application의 실 트래픽을 수집·관찰할 수 있습니다.
***
### 🔗 관련 문서
* G-1. Workspace 생성 — 평가 작업을 수행할 Workspace 생성
* G-2. User 관리 — Workspace에 사용자 초대 및 권한 부여
* G-3. Gen\&Judge 모델 등록 — 평가에 사용할 Gen/Judge 모델 설정
* G-4. Application 생성 — 평가 대상 Application 등록