TypeSafe の API

HTTP評価エンドポイント

リクエスト本文には3つのトップレベルフィールドがあります。stateは必須で、文字列、オブジェクト、またはテキスト配列を指定できます。modelも必須で、ドキュメントの例ではjev-latestを使用します。questionsは、型付きQuestionオブジェクトのマップです。各キーは任意に決められ、対応する回答が同じIDで返されます。キーは基盤モデルに送信されず、推論にも使われません。

最小構成のNoulは、{"state": "助けてください！支払いが3日間失敗し続けています。", "model": "jev-latest", "questions": {"is_urgent": {"type": "noul", "instructions": "緊急性が伝わりますか？"}}}のようになります。Choiceでは、選択肢名から説明への基準マップを追加します。Scoreでは、レベルを並べた基準配列を追加します。3種類すべてにtypeとinstructionsがあり、それぞれ固有の形式のcriteriaを加えます。

https://console.typesafe.ai/settings/keys.でAPIキーを取得します。HTTPを直接呼び出す場合、429ではretry-afterに従って再試行してください。Jev 1.13のレート制限は毎秒250,000トークン、毎分1,200リクエストで、予告なく変更される場合があります。SDKはデフォルトでバックオフ付き再試行を行います。モデル一覧は同じBearerトークンを使い、GET /v1/modelsで取得します。

公式SDK

Python：pip install typesafe-sdk。typesafe_sdkからTypeSafeClientをインポートします。TypeSafeClient()をclientとして使用し、client.system_one(state, questions)を呼び出します。Noul、Choice、Scoreなどのコンストラクターはパッケージに含まれるため、JSONのtypeフィールドを手書きする必要はありません。デフォルトモデルはjev-latestです。Python 3.10以降が必要です。

JavaScript：npm install @typesafe-ai/sdk。"@typesafe-ai/sdk"から{ TypeSafeClient }をインポートします。このクライアントも同じエンドポイントを使用します。実行環境はNode.js 20+です。リポジトリはhttps://github.com/typesafe-ai/typesafe-sdk-js.です。両SDKともエイリアス一覧用のmodels.list()を提供します。

https://console.typesafe.ai/playgroundのプレイグラウンドはログインが必要なコンソールで、公開埋め込みではありません。テキストをstateとして貼り付け、「このメッセージは緊急性を示しているか？」のようなNoulを追加し、さらに複数の質問を1回の呼び出しにまとめます。本番用キーを組み込む前に、並列評価を最も手早く体感できます。

最初のcurl

Authorization: Bearer $TYPESAFE_API_KEYとContent-Type: application/jsonを付けて、curl -X POST https://api.typesafe.ai/v1/systemoneを実行します。本文には、Stripe Connectの障害メッセージをstateとして指定し、modelにjev-latest、questions.urgencyにtype noulとinstructions「このメッセージは緊急性を示していますか？」を設定します。これがクイックスタートのサンプルです。さらにdepartmentというChoiceにbilling / technical / salesの基準を、frustrationというScoreに順序付きレベルを追加できます。2回目の往復は不要です。

問題が起きたら、指示文を長くする前にjaggednessを確認してください。字面どおりの判定には、指示と基準に条件を明記する必要があります。計算や数え上げはコードで行い、文章生成には別のモデルを使います。連鎖したChoiceでJevに段落を書かせても、APIは型付きペイロードを返しますが、遅いうえに品質も低くなります。正規表現または生成モデルで候補を作り、Jevに選ばせてください。

Cloudflare Workers AIでは、カタログ名としてtypesafe/jevが掲載されています。これはサードパーティの掲載であり、api.typesafe.aiの代替ではありません。SteamにJevアプリはありません。キーはTypeSafeのコンソールで管理し、Awesome JevのコミュニティSDKは、github.com/typesafe-ai組織を追随していない限り非公式として扱ってください。

エラー、再試行、ID

毎秒トークン数または毎分リクエスト数を超えた場合、文書化されている応答は429 Too Many Requestsです。retry-afterに従ってください。公式SDKはすでにバックオフを行います。HTTPを独自にラップする場合、429でエンドポイントを連打しないでください。同じ制限時間枠にとどまるだけです。

質問IDはトレース用で、推論には一切入りません。ループでitem_0からitem_nまで生成しても、それぞれ1つのNoulが返ります。リクエスト内ではキーを一意にしてください。同じキーを再利用すると、マップ内の質問が通知なく上書きされます。

認証には、ダッシュボードで発行したBearer TypeSafe APIキーを使用します。api.typesafe.aiにはCookieセッションがありません。キーのローテーションは、このWikiへのメールではなくコンソールで行ってください。プレイグラウンドのログイン制限は別物で、ブラウザー用コンソールであり、代替のHTTP APIではありません。

クイックスタートのcurlを一度コピーしたら、リポジトリから削除してSDKへ置き換えてください。再試行と型付きコンストラクターはSDKが処理します。生のHTTPは、公式クライアントがない言語向けです。どちらの方法でもBearerキーと同じJSON本文をPOST /v1/systemoneへ送信します。

GET /v1/modelsは、アカウントから送信可能なエイリアスを一覧表示します。POST /v1/systemoneでそのIDが使えても、jev-1.13.0が一覧に出ない場合があります。この一覧をバージョン付きIDの許可リストと見なさないでください。エイリアス一覧として扱い、バージョン付きIDは独自の設定に保持します。

TYPESAFE_API_KEYは絶対にコミットしないでください。漏えいした場合はダッシュボードでローテーションします。漏えいした秘密情報の連絡先としてcontact@jevai.wikiは不適切です。TypeSafeの公式窓口を利用してください。

Python 3.10とNode.js 20が、ドキュメント記載の最低要件です。それより古い実行環境は公式クライアントの対象外です。