Humanloop

Humanloop

Humanloop는 기업용 LLM 애플리케이션을 평가(Evaluation), 프롬프트 관리(Prompt Management), 관측성(Observability) 관점에서 관리하는 플랫폼이에요. LLM 기반 AI 기능을 만들 때 프롬프트를 반복 개선하고, 평가를 코드/UI에서 실행하며, 배포 후에는 성능을 실시간으로 모니터링할 수 있게 해 줘요. 평가 주도 개발(evals-driven development)과 엔지니어·도메인 전문가의 협업 개발이라는 두 가지 베스트 프랙티스를 플랫폼 하나로 지원합니다.

참고: Humanloop 플랫폼은 2025년 9월 8일자로 sunset(서비스 종료) 예정이며, 데이터를 내보내려면 공식 Migration Guide를 참조하는 게 좋아요.

출처: 문서

본문

SDK 설치와 초기화

먼저 Humanloop SDK를 설치하고 API 키로 초기화해요. API 키는 Organization Settings에서 발급받을 수 있어요.

pip install humanloop

npm install humanloop

from humanloop import Humanloop
humanloop = Humanloop(api_key="<YOUR HUMANLOOP KEY>")

# Check that the authentication was successful
print(humanloop.prompts.list())

import { HumanloopClient, Humanloop } from "humanloop";

const humanloop = new HumanloopClient({ apiKey: *** });

// Check that the authentication was successful
console.log(await humanloop.prompts.list());

LLM 평가 (Evals)

평가 프레임워크의 핵심은 Evaluator예요. LLM이 생성한 Log를 입력으로 받아 **판정(judgment)**을 돌려주는 함수죠. 판정은 보통 boolean이거나 숫자 형태라서, 사용 사례에 맞는 기준으로 모델 성능을 판단할 수 있어요.

Evaluator의 판정 소스는 세 가지가 있어요.

  • Code — 비용·토큰 사용량·지연·출력 regex 등 결정적 규칙 기반 판정. 빠르고 저렴해서 대규모로 돌리기 좋아요.
  • AI — 다른 파운데이션 모델이 출력을 평가. 사람 판정 비용의 일부로 더 질적이고 미묘한 판정을 내려요.
  • Human — 최종 사용자나 내부 도메인 전문가의 골드 스탠다드 판정. 가장 비싸고 느리지만 가장 신뢰할 수 있어요.

Evaluator는 두 가지 방식으로 활용돼요.

  • 온라인 모니터링(Online Monitoring) — 배포된 프롬프트에 온라인 Evaluator를 붙이면 새 Log가 생길 때마다 자동으로 실행돼요. 시간에 따른 성능 변화·드리프트를 추적하고 알림을 걸 수 있어요.
  • 오프라인 평가(Offline Evaluations) — 정해진 Dataset과 결합해서 개발 중에 버전을 비교하거나, CI 환경에서 회귀(regression)를 테스트해요.

Evaluator의 판정 반환 타입은 Boolean, Number, Select, Multi-select, Text가 있어요. Code·AI Evaluator는 Boolean/Number를, Human Evaluator는 Number/Select/Multi-select/Text를 반환할 수 있어요.

코드로 평가 실행하기

humanloop.evaluations.run으로 평가를 실행할 수 있어요. 실행 대상 함수(callable), 테스트용 dataset, 판정을 내릴 evaluators 목록을 넘기면 되고, 실행 결과로 evaluator별 점수가 담긴 checks 객체가 반환돼요.

from humanloop import Humanloop

humanloop = Humanloop(api_key="<YOUR HUMANLOOP KEY>")

checks = humanloop.evaluations.run(
  name="Initial Test",
  file={
      "path": "Scifi/App",
      # Replace with your AI model
      "callable": lambda messages: (
          "I'm sorry, Dave. I'm afraid I can't do that."
          if messages[-1]["content"].lower() == "hal"
          else "Beep boop!"
      )
  },
  # Replace with your test dataset
  dataset={
      "path": "Scifi/Tests",
      "datapoints": [
        {
          "messages": [
            {
              "role": "system",
              "content": "You are an AI that responds like famous sci-fi AIs."
            },
            {
              "role": "user",
              "content": "HAL"
            }
          ],
          "target": {
            "output": "I'm sorry, Dave. I'm afraid I can't do that."
          }
        },
        {
          "messages": [
            {
              "role": "system",
              "content": "You are an AI that responds like famous sci-fi AIs."
            },
            {
              "role": "user",
              "content": "R2D2"
            }
          ],
          "target": {
            "output": "Beep boop beep!"
          }
        }
      ]
  }, 
  evaluators=[
      {"path": "Example Evaluators/Code/Exact match"},
      {"path": "Example Evaluators/Code/Latency"},
      {"path": "Example Evaluators/AI/Semantic similarity"},
  ],
)

import { HumanloopClient } from "humanloop";

const humanloop = new HumanloopClient({
  apiKey: *** HUMANLOOP KEY>",
});

const checks = humanloop.evaluations.run({
  name: "Initial Test",
  file: {
    path: "Scifi/App",
    // Replace with your AI model
    callable: (inputs, messages) =>
      messages && messages[messages.length - 1].content.toLowerCase() === "hal"
        ? "I'm sorry, Dave. I'm afraid I can't do that."
        : "Beep boop!",
  },
  // Replace with your test dataset
  dataset: {
    path: "Scifi/Tests",
    datapoints: [
      {
        messages: [
          {
            role: "system",
            content: "You are an AI that responds like famous sci-fi AIs.",
          },
          {
            role: "user",
            content: "HAL",
          },
        ],
        target: { output: "I'm sorry, Dave. I'm afraid I can't do that." },
      },
      {
        messages: [
          {
            role: "system",
            content: "You are an AI that responds like famous sci-fi AIs.",
          },
          {
            role: "user",
            content: "R2D2",
          },
        ],
        target: { output: "Beep boop beep!" },
      },
    ],
  },
  evaluators: [
    { path: "Example Evaluators/Code/Exact match" },
    { path: "Example Evaluators/Code/Latency" },
    { path: "Example Evaluators/AI/Semantic similarity" },
  ],
});

실행하면 터미널에 결과 URL이 표시되고, 반복 실행할 때마다 Humanloop UI의 Stats 뷰에 실행 컬럼이 추가돼서 시간에 따른 성능 변화를 비교할 수 있어요.

프롬프트 관리 (Prompt Management)

Prompt(대문자 P)는 LLM이 특정 작업을 수행하도록 안내하는 지시와 설정을 정의하는 Humanloop의 핵심 엔티티예요. 다음 속성 중 하나라도 바뀌면 새 Version이 생성돼요.

  • template — 예: Write a song about {{topic}} (챗 모델은 메시지 배열)
  • model — 예: gpt-4o
  • parameters — temperature, max_tokens, top_p 등 모델 파라미터
  • tools — 모델에 제공할 도구

입력 변수는 {{topic}}처럼 이중 중괄호 문법으로 템플릿에 정의하고, 호출 시점에 값을 넣어요. 이렇게 설정과 쿼리 시점 데이터를 분리하는 게 중요해서, 설정을 바꿔가며 실험하고 변화를 평가할 수 있어요.

---
model: gpt-4o
temperature: 1.0
max_tokens: -1
provider: openai
endpoint: chat
---
<system>
  Write a song about {{topic}}
</system>

프롬프트는 API로 호출 가능해요.

import requests

url = "https://api.humanloop.com/v5/prompts/call"

payload = { "stream": True }
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

import { HumanloopClient } from "humanloop";

const client = new HumanloopClient({ apiKey: *** });
const response = await client.prompts.callStream({});
for await (const item of response) {
    console.log(item);
}

데이터셋 (Datasets)

Dataset은 평가와 파인튜닝에 쓰는 Datapoint의 모음이에요. Datapoint는 전통적인 프로그래밍의 단위 테스트처럼 생각하면 돼요. 다음 필드를 가져요.

  • Inputs — 템플릿의 {{variables}}를 대체하는 프롬프트 변수 값 모음
  • Messages — 챗 모델용 채팅 메시지 히스토리
  • Target — 기대 출력 문자열. 고급 사례에서는 평가에 필요한 필드를 담은 JSON 객체로 정의 가능

Dataset도 버전 관리가 되고, Datapoint 내용이 바뀌면 새 Version이 생겨요. 각 평가(Evaluation)는 특정 Dataset Version에 연결돼서, 평가 결과가 항상 정확한 테스트 케이스 집합에 추적 가능하게 해 줘요.

트레이싱과 Flows

LLM 기반 시스템은 보통 여러 단계를 거쳐요. Flows는 AI 기능 진입점에 데코레이터를 붙여 모든 컴포넌트를 트레이싱하고, 관련 Log를 한눈에 볼 수 있는 종합 뷰로 통합해 주고, 에이전트부터 RAG까지 복잡한 AI 워크플로를 디버깅·평가할 수 있게 해 줘요.

@humanloop.flow(path="QA Agent/Answer Question")
def call_agent(question: str) -> str:
    # A simple question answering agent

    ...

    return answer

const callAgent = humanloop.flow({
    path: "QA Agent/Answer Question",
    callable: async (question: string) => {
        // A simple question answering agent

        ...

        return answer
    }
})

트레이스에는 추가 Log도 붙일 수 있어요. call_agent 안에서 다른 함수(예: search_wikipedia 툴, call_model 프롬프트)를 호출하면 각각 Log가 생기고 call_agent가 만든 트레이스에 추가돼요.

@humanloop.tool(path="QA Agent/Search Wikipedia")
def search_wikipedia(query: str) -> dict:
    """LLM function calls this to search Wikipedia."""
    ...


@humanloop.prompt(path="QA Agent/Call Model")
def call_model(messages: list[dict]) -> dict:
    """Interact with the LLM model."""
    ...


@humanloop.flow(
    path="QA Agent/Answer Question",
    attributes={"version": "v1", "wikipedia": True}
)
def call_agent(question: str) -> str:
    """A simple question answering agent."""
    ...

관측성 (Observability)과 모니터링

배포 후에는 프롬프트에 온라인 Evaluator를 연결해서 실시간 성능을 측정해요. Prompt의 대시보드에서 Monitoring → Connect Evaluators로 Evaluator를 붙이고 "Auto-run"을 켜면, 새 Log가 생길 때마다 Evaluator가 자동 실행돼요.

  • Dashboard 탭 — 시간에 따른 평균 Evaluator 결과를 그래프로 보여줘요. 기간과 해상도를 조절해서 성능 추이를 확인할 수 있어요.
  • Logs 탭 — 프롬프트가 생성한 각 Log의 Evaluator 결과를 확인하고, select/multi_select 타입 Evaluator는 옵션으로 필터링할 수 있어요.

모니터링 Evaluator는 패치된 Log, 그리고 트레이스에 새 Log가 추가된 Flow·Agent Log에 대해 다시 실행돼서 판정이 항상 최신 Log 상태를 반영하게 해 줘요.

더 알아보기 (Learn more)