API 레퍼런스

TypeSafe 평가 엔드포인트의 전체 HTTP API 레퍼런스입니다.

state를 타입이 지정된 questions 맵에 대해 평가하고, 질문마다 하나씩 구조화된 answers를 돌려받습니다. 안내식 소개는 프리미티브부터 시작하십시오.

평가 엔드포인트

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

요청 본문

모든 요청의 최상위 형태입니다. questions 맵의 각 항목은 여러분이 이름을 붙인 타입 지정 질문입니다.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

질문 유형

Question은 type 필드로 정해지는 세 가지 유형 중 하나입니다. 세 유형 모두 type과 instructions를 공유하며, 각자 고유한 criteria를 추가합니다.

instructions 속성은 문자열, 객체, 또는 배열일 수 있습니다. 추가 컨텍스트나 참조해야 할 데이터가 있는 긴 질문은 구조화된 객체로 나눌 수 있습니다. 질문은 한 필드에, 데이터는 다른 필드에 넣고, 중첩된 state 값을 가리키는 방식과 같은 방식으로 데이터 필드를 이름으로 백틱 안에서 참조하십시오:

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

자세한 내용은 질문에 구조 사용하기를 참조하십시오.

Noul

yes/no 질문입니다. 답이 yes일 확률을 반환합니다.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice

여러분이 정의한 집합에서 선택지 하나를 고릅니다. 선택된 선택지와 전체 확률 분포를 반환합니다.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score

여러분이 정의한 루브릭을 따라 상태를 평가합니다. 레벨에 걸쳐 확률 가중치를 적용한 값을 반환합니다.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

응답 본문

질문마다 하나의 답변이며, 여러분이 제공한 것과 같은 id 아래에 반환됩니다.

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

답변 유형

모든 답변은 해당 질문과 일치하는 type을 가집니다. Choice와 Score 답변은 또한 답변의 확률 분포에서 도출된 0에서 1 사이의 confidence를 가집니다. 신뢰도를 참조하십시오.

Noul 답변

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Choice 답변

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Score 답변

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

오류

오류는 무엇이 잘못되었는지 설명하는 JSON 본문과 함께 표준 HTTP 상태 코드를 사용합니다.

속도 제한 처리

429 Too Many Requests 또는 529 Overloaded 응답을 받으면 즉시 재시도하지 말고 지수 백오프로 요청을 재시도하십시오. 저희 클라이언트 SDK는 이를 자동으로 처리하므로, 기본 재시도 정책을 사용하는 저희 SDK 중 하나를 사용한다면 별도의 처리가 필요하지 않습니다.