AI Connections

AI Connections

코드를 작성하지 않고 AI 앱을 연결해 플랫폼에서 바로 평가(evaluation)를 실행할 수 있게 해주는 기능이에요. HTTPS 엔드포인트로 AI 앱에 연결해 평가를 직접 실행해요. 코드를 쓰는 대신 버튼 한 번으로 평가를 트리거할 수 있고, Confident AI가 골든(golden) 데이터로 엔드포인트를 호출해 그 응답을 파싱해요.

출처: 문서

본문

Setup AI Connection

AI Connection 설정하기 (Setting Up an AI Connection)

AI connection을 만들려면:

1. Project Settings(프로젝트 설정) → AI Connections로 이동
2. New AI Connection 클릭
3. 고유한 식별 이름 부여
4. Save(저장) 클릭

아직은 AI connection을 사용할 수 없어요. 엔드포인트, 페이로드, 그리고 최소한 실제 출력 키 경로는 구성해야 해요.

엔드포인트 구성하기 (Configuring Your Endpoint)

AI connection을 AI 앱의 HTTPS 엔드포인트로 연결해요. 엔드포인트는 POST 요청을 반드시 받아야 하고, AI 앱의 실제 출력을 담은 응답을 돌려줘야 해요.

엔드포인트가 응답하는 방식에 따라 응답 모드를 선택해요.

• HTTP Response: 실제 출력을 담은 단일 응답을 돌려줌 (기본값).
• HTTP Streaming: 줄바꿈으로 구분된 청크(chunk) 스트림을 돌려줌.
• SSE Streaming: Server-Sent Events 스트림을 돌려줌.

스트리밍 엔드포인트는 Streaming에서 청크 형식·SSE 이벤트 이름·accumulate 모드를 구성해요. 응답에 몇 분에서 몇 시간이 걸리는 에이전트는 Async Responses를 참고해 각 요청을 즉시 승인하고 나중에 결과를 다시 올리세요.

페이로드 (Payload)

페이로드는 Confident AI가 엔드포인트를 호출할 때 보내는 요청 본문이에요. JSON 모드는 사용 가능한 변수들을 JSON 구조로 매핑할 수 있게 해주고, Code 편집기는 조건부 로직·데이터 변환·요청 본문의 완전한 프로그래매틱 제어를 위한 Python 함수를 작성할 수 있게 해줘요.

JSON

JSON 모드는 사용 가능한 변수들로 페이로드를 정의하게 해줘요. 엔드포인트가 기대하는 구조에 맞게 값을 중첩할 수 있어요.

Map golden variables into a JSON payload

사용 가능한 변수:

Variable	Description	Type
golden.input	The input from your golden	string
golden.actual_output	The actual output from your golden	string
golden.expected_output	The expected output from your golden	string
golden.retrieval_context	The retrieval context from your golden	string[]
golden.context	The context from your golden	string[]
golden.expected_tools	The expected tools from your golden	ToolCall[]
golden.tools_called	The tools called from your golden	ToolCall[]
golden.additional_metadata	Additional metadata from your golden	object
conversationalGolden.turns	Turn history for multi-turn evals	Turn[]
conversationalGolden.context	Context for conversational goldens	string[]
conversationalGolden.scenario	Scenario for conversational goldens	string
conversationalGolden.expected_outcome	Expected outcome for conversational goldens	string
conversationalGolden.user_description	User description for conversational goldens	string
conversationalGolden.additional_metadata	Additional metadata for conversational goldens	object
prompts	A dictionary of prompts	object
hyperparameters	A dictionary of hyperparameter key-value pairs	object
testCaseId	Unique identifier for linking traces to test cases	string
turnId	Unique identifier for linking traces to turns	string
state	An object to keep state for multi-turn simulations	object

단일 턴(single-turn) 평가에는 golden.* 변수를, 멀티 턴(multi-turn) 평가에는 conversationalGolden.* 변수를 사용해요. prompts 딕셔너리 사용법은 Prompts를, 엔드포인트에 하이퍼파라미터를 전달하는 법은 Hyperparameters를 참고하세요.

예시 페이로드:

{
  "input": golden.input,
  "context": golden.context,
  "conversationalContext": conversationalGolden.context,
  "prompts": prompts,
  "hyperparameters": hyperparameters,
  "turns": conversationalGolden.turns
}

커스텀 페이로드 기능을 쓰면 기존 API 계약에 맞게 요청을 구성할 수 있어요. 특정 형식을 받으려고 AI 앱을 수정할 필요가 없어요.

Code

Code 모드는 generate_payload 함수를 정의하는 내장 Python 편집기를 제공해요. 이 함수는 golden 인자(Union[Golden, ConversationalGolden]로 타이핑됨)와 함께 prompts, hyperparameters, testCaseId, turnId, state를 받아요. isinstance 검사로 단일 턴과 멀티 턴 골든을 다르게 처리하면 돼요.

Write a Python function to build the payload

golden이 Golden일 때 사용 가능한 속성:

Variable	Description	Type
golden.input	The input from your golden	string
golden.actual_output	The actual output from your golden	string
golden.expected_output	The expected output from your golden	string
golden.retrieval_context	The retrieval context from your golden	string[]
golden.context	The context from your golden	string[]
golden.expected_tools	The expected tools from your golden	ToolCall[]
golden.tools_called	The tools called from your golden	ToolCall[]
golden.additional_metadata	Additional metadata from your golden	object

golden이 ConversationalGolden일 때 사용 가능한 속성:

Variable	Description	Type
golden.turns	Turn history for multi-turn evals	Turn[]
golden.context	Context for conversational goldens	string[]
golden.scenario	Scenario for conversational goldens	string
golden.expected_outcome	Expected outcome for conversational goldens	string
golden.user_description	User description for conversational goldens	string
golden.additional_metadata	Additional metadata for conversational goldens	object

추가 파라미터:

Parameter	Description	Type
prompts	A dictionary of prompts	Optional[Dict[str, str]]
hyperparameters	A dictionary of hyperparameter key-value pairs	Optional[Dict[str, str]]
testCaseId	Unique identifier for linking traces to test cases	Optional[str]
turnId	Unique identifier for linking traces to individual turns in multi-turn evals	Optional[str]
state	An object to keep state for multi-turn simulations	Optional[Any]

from deepeval import Golden, ConversationalGolden

def generate_payload(
    golden: Union[Golden, ConversationalGolden],
    prompts: Optional[Dict[str, str]] = None,
    hyperparameters: Optional[Dict[str, str]] = None,
    testCaseId: Optional[str] = None,
    turnId: Optional[str] = None,
    state: Optional[Any] = None,
) -> dict:

    if isinstance(golden, Golden):
        return {
            "input": golden.input,
            "context": golden.context,
            "prompts": prompts,
            "hyperparameters": hyperparameters
        }

    elif isinstance(golden, ConversationalGolden):
        return {
            "turns": golden.turns,
            "conversationContext": golden.context,
            "prompts": prompts,
            "hyperparameters": hyperparameters
        }

함수가 반환하는 값이 엔드포인트로 보내는 POST 본문이 돼요.

Code 모드는 AI 앱이 평가 유형에 따라 다른 페이로드 형태를 기대할 때, 보내기 전에 골든 데이터를 전처리해야 할 때, 또는 UUID나 타임스탬프 같은 동적 값을 즉석에서 생성해야 할 때 특히 유용해요.

출력 파싱 (Output Parsing)

엔드포인트가 응답을 반환하면, Confident AI는 그 응답에서 관련 값을 어떻게 뽑아낼지 알아야 해요. JSON 응답의 특정 값을 가리키려면 **키 경로(key path)**를, 커스텀 로직으로 추출해야 하면 **트랜스포머(transformer)**를 사용해요.

• Actual Output Key Path: 실제 출력을 찾을 위치 (필수)
• Retrieval Context Key Path: 검색 컨텍스트를 찾을 위치 (선택, RAG 메트릭용)
• Tool Call Key Path: 호출된 도구를 찾을 위치 (선택, 도구 관련 메트릭용)

Key paths support both JSON keys (strings) and list indices (integers)

Actual Output Key Path

JSON 응답에서 actual_output 값까지의 경로를 나타내는 문자열 또는 정수 목록이에요. JSON 키에는 문자열을, 배열 인덱스에는 정수를 사용해요. 평가가 동작하려면 필수예요.

예를 들어 엔드포인트가 이렇게 반환하면:

{
  "response": {
    "output": "Hello, world!"
  }
}

키 경로를 ["response", "output"]으로 설정해요.

중첩 배열에는 정수로 배열 인덱스를 지정해요. 예를 들어 엔드포인트가 이렇게 반환하면:

{
  "response": {
    "output": {
      "content": [{ "text": "Hello, world!" }]
    }
  }
}

키 경로를 ["response", "output", "content", 0, "text"]으로 설정해요.

Retrieval Context Key Path

JSON 응답에서 retrieval_context 값까지의 경로를 나타내는 문자열 또는 정수 목록이에요. JSON 키에는 문자열을, 배열 인덱스에는 정수를 사용해요. 선택 사항이며 RAG 메트릭을 쓸 때만 필요해요. 값은 문자열 목록이어야 해요.

예를 들어 엔드포인트가 이렇게 반환하면:

{
  "response": {
    ...
    "retrieval_context": ["context1", "context2"]
  }
}

키 경로를 ["response", "retrieval_context"]으로 설정해요.

Tool Call Key Path

JSON 응답에서 tools_called 값까지의 경로를 나타내는 문자열 또는 정수 목록이에요. JSON 키에는 문자열을, 배열 인덱스에는 정수를 사용해요. 선택 사항이며 tool call 파라미터를 요구하는 메트릭을 쓸 때만 필요해요. 값은 ToolCall 목록이어야 해요.

예를 들어 엔드포인트가 이렇게 반환하면:

{
  "response": {
    ...
    "tools_called": [
      {
        "name": "get_weather",
        "description": "Get weather for a location",
        "reasoning": "User asked about the weather in San Francisco",
        "output": "Sunny, 72°F",
        "inputParameters": {"location": "San Francisco"}
      }
    ]
  }
}

키 경로를 ["response", "tools_called"]으로 설정해요.

tool call의 구조에 대해 더 자세히 알고 싶다면 공식 DeepEval 문서를 참고하세요.

트랜스포머 (Transformers)

키 경로로 충분하지 않을 때 — 예를 들어 엔드포인트가 커스텀 로직이 필요한 비표준 형식을 반환할 때 — 트랜스포머를 사용해 자체 Python 코드로 실제 출력을 추출해요.

파서를 JSON Key Path에서 Transformer로 전환하면 키 경로 대신 트랜스포머를 선택할 수 있어요.

Use a transformer for custom extraction logic

자체 트랜스포머를 추가하려면 Project Settings(프로젝트 설정) → Transformers로 가서 Create Transformer를 클릭해요. 자세한 내용은 Transformers를 참고하세요.

헤더 (Headers)

엔드포인트가 필요로 하는 커스텀 헤더를 키-값 쌍으로 추가해요 — API 키, bearer 토큰, Content-Type 같은 것들이에요. 여기에 추가한 내용은 Confident AI가 AI 앱에 보내는 모든 요청에 포함돼요.

Add custom headers sent with every request

설정할 수 있는 일반적인 헤더:

• Authorization — 정적 API 키 또는 bearer 토큰 (예: Bearer sk-...)
• Content-Type — 요청 본문의 형식 (예: application/json)
• 엔드포인트가 기대하는 커스텀 헤더 (예: X-API-Key)

시크릿 매니저나 서명된 요청이 필요한 인증은 헤더에 자격 증명을 하드코딩하는 대신 Authorization을 사용하세요.

연결 테스트하기 (Testing Your Connection)

Ping Endpoint를 클릭해 모든 것이 올바르게 설정되었는지 확인해요. 200 상태 응답을 받아야 해요. 받지 못한다면 오류 메시지를 확인하고 구성을 조정하세요.

✅ 완료 — 이제 AI connection으로 평가를 실행할 준비가 됐어요.

다음 단계 (Next Steps)

AI connection을 설정했으니, 이제 프로덕션 준비를 만드는 구성 요소들을 살펴볼게요.

Prompts & Hyperparameters

프롬프트 버전과 하이퍼파라미터를 연결하고, 모든 테스트 런에 기록해요.

Streaming

HTTP Streaming이나 SSE로 출력을 스트리밍하고, 이벤트 이름과 accumulate 모드를 설정해요.

Async Responses

각 요청을 승인하고 나중에 결과를 다시 올려 오래 실행되는 에이전트를 평가해요.

Authorization

시크릿 매니저와 Auth0 또는 HMAC 인증으로 요청을 보호해요.

Throttling & Retries

엔드포인트 요청의 동시성·타임아웃·재시도를 조정해요.

Multi-Generation

골든마다 앱을 여러 번 샘플링해 통계적으로 엄밀한 테스트 런을 만들어요.

Multi-Turn State

멀티 턴 시뮬레이션 동안 턴을 가로질러 정보를 유지해요.

Linking Traces

테스트 케이스와 턴을 그 트레이스에 연결해 완전한 관측성을 확보해요.

Confident Agent

인바운드 포트를 열지 않고 방화벽 뒤의 내부 엔드포인트에 도달해요.

더 알아보기 (Learn more)

• Streaming 응답
• Async Responses
• Authorization