出力フォーマット

Rustellar AI モデルからのレスポンス構造を理解します。

レスポンス構造

すべての API レスポンスは一貫した JSON フォーマットに従います。

標準レスポンス

{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "helix-v1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 9,
    "total_tokens": 19
  }
}

レスポンスフィールド

トップレベルフィールド

フィールド	型	説明
id	string	補完の一意識別子
object	string	常に "chat.completion"
created	integer	作成時間の Unix タイムスタンプ
model	string	生成に使用されたモデル
choices	array	補完の選択肢の配列 (通常は 1 つ)
usage	object	トークン使用量情報

Choice オブジェクト

フィールド	型	説明
index	integer	選択肢のインデックス (0 から開始)
message	object	生成されたメッセージ
finish_reason	string	補完が終了した理由

Message オブジェクト

フィールド	型	説明
role	string	レスポンスの場合は常に "assistant"
content	string	実際に生成されたテキスト

Usage オブジェクト

フィールド	型	説明
prompt_tokens	integer	プロンプトのトークン数
completion_tokens	integer	補完のトークン数
total_tokens	integer	使用された総トークン数 (プロンプト + 補完)

終了理由

finish_reason フィールドは、生成が停止した理由を示します:

理由	説明
stop	自然な停止点に達した
length	最大トークン数制限に達した
content_filter	ポリシーによりコンテンツがフィルタリングされた
null	まだ生成中 (ストリーミングモード)

ストリーミングレスポンス

リアルタイム出力には、ストリーミングモードを使用します。

ストリーミングの有効化

import requests

# ストリーミングモードを有効化
response = requests.post(
    "https://api.rustellar.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "helix-v1",
        "messages": [
            {"role": "user", "content": "Tell me a story"}
        ],
        "stream": True  # ストリーミングを有効化
    },
    stream=True  # requests.postでストリーミングレスポンスを受信
)

# ストリーミングデータを逐次処理
for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))

ストリーミングレスポンスフォーマット

各チャンクは次のフォーマットに従います:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"helix-v1","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"helix-v1","choices":[{"index":0,"delta":{"content":" there"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"helix-v1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

ストリーミングレスポンスの処理

import json

def process_stream(response):
    """ストリーミングレスポンスを処理する関数"""
    for line in response.iter_lines():
        if line:
            # "data: " プレフィックスを除去
            line_text = line.decode('utf-8')
            if line_text.startswith('data: '):
                data = line_text[6:]  # "data: " を削除

                # 終了シグナルをチェック
                if data == '[DONE]':
                    break

                # JSONをパース
                try:
                    chunk = json.loads(data)
                    # デルタコンテンツを取得
                    delta = chunk['choices'][0]['delta']
                    if 'content' in delta:
                        print(delta['content'], end='', flush=True)
                except json.JSONDecodeError:
                    continue

# 使用例
response = requests.post(
    "https://api.rustellar.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "helix-v1",
        "messages": [{"role": "user", "content": "Write a poem"}],
        "stream": True
    },
    stream=True
)

process_stream(response)

エラーレスポンス

エラーが発生すると、API はエラーオブジェクトを返します:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

一般的なエラーコード

コード	説明
invalid_api_key	無効または欠落している API キー
rate_limit_exceeded	リクエスト数が多すぎる
invalid_request_error	不正なリクエスト形式
model_not_found	指定されたモデルが存在しない
context_length_exceeded	入力がモデルのコンテキストウィンドウを超えている

エラーハンドリングの例

import requests

def make_api_call(messages):
    """エラーハンドリング付きAPI呼び出し"""
    try:
        response = requests.post(
            "https://api.rustellar.com/v1/chat/completions",
            headers={
                "Authorization": "Bearer YOUR_API_KEY",
                "Content-Type": "application/json"
            },
            json={
                "model": "helix-v1",
                "messages": messages
            }
        )

        # HTTPステータスコードをチェック
        response.raise_for_status()

        # レスポンスをパース
        data = response.json()
        return data['choices'][0]['message']['content']

    except requests.exceptions.HTTPError as e:
        # HTTPエラーを処理
        error_data = e.response.json()
        print(f"API Error: {error_data['error']['message']}")
        return None

    except Exception as e:
        # その他のエラーを処理
        print(f"Error: {str(e)}")
        return None

# 使用例
result = make_api_call([
    {"role": "user", "content": "Hello!"}
])

if result:
    print(result)

ベストプラクティス

1. finish_reason を常に確認して生成が停止した理由を理解する
2. トークン使用量を監視してコストを制御する
3. エラーハンドリングを実装して堅牢なアプリケーションを構築する
4. 長い応答にはストリーミングを使用してユーザーエクスペリエンスを向上させる
5. レスポンスを安全にパースして try-catch ブロックを使用する

次のステップ

• 入力フォーマットを確認
• レート制限を確認
• モデルを探索