Chat Completions

YouRouter でチャットモデルを使う主な方法は次の 2 つです。

OpenAI 互換 API：ほとんどの用途で推奨。統一インターフェースで多モデルを扱えます。
プロバイダー固有 API：統一 API に無い上流固有機能が必要な上級用途向け。

モデルとプロバイダーの選び方はルーティングを参照してください。

OpenAI 互換 API

最もシンプルで柔軟な方法です。慣れた OpenAI SDK を使いつつ、モデルや上流を最小限の変更で切り替えられます。

基本的な使い方

次の例は、基本的な chat completion リクエストを送る方法です。model と vendor ヘッダーを変更することで、別のモデルやプロバイダーを指定できます。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUROUTER_API_KEY"],
    base_url="https://api.yourouter.ai/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
    ],
    extra_headers={"vendor": "openai"}
)

print(response.choices[0].message.content)

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.YOUROUTER_API_KEY,
  baseURL: 'https://api.yourouter.ai/v1',
});

const completion = await openai.chat.completions.create({
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' }
  ],
  model: 'claude-3-5-sonnet-20240620',
  extraHeaders: { vendor: 'anthropic' }
});

console.log(completion.choices[0].message.content);

curl https://api.yourouter.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -H "vendor: google" \
  -d '{
    "model": "gemini-1.5-pro-latest",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

高度な機能

マルチターン会話

継続的な会話を維持するには、それまでの会話履歴全体を messages 配列に渡します。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUROUTER_API_KEY"],
    base_url="https://api.yourouter.ai/v1"
)

messages = [
    {"role": "system", "content": "You are a witty assistant that tells jokes."},
    {"role": "user", "content": "Tell me a joke about computers."},
    {"role": "assistant", "content": "Why did the computer keep sneezing? It had a virus!"},
    {"role": "user", "content": "That was a good one. Tell me another."}
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages
)

print(response.choices[0].message.content)

ストリーミング

チャットボットなどのリアルタイム用途では、生成中のレスポンスをストリーミングできます。リクエストで stream=True を設定します。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUROUTER_API_KEY"],
    base_url="https://api.yourouter.ai/v1"
)

stream = client.chat.completions.create(
    model="claude-3-haiku-20240307",
    messages=[{"role": "user", "content": "Write a short poem about the ocean."}],
    stream=True,
    extra_headers={"vendor": "anthropic"}
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

関数呼び出し / ツール利用

モデルにツールや関数を使わせ、外部システムと連携できます。一般的な流れは次の複数ステップです。

利用可能なツール一覧を含めてリクエストを送ります。
モデルが、呼び出したい 1 つ以上のツールを返します。
アプリケーション側のコードでツールを実行します。
ツールの実行結果をモデルへ返し、モデルが最終的な自然言語の回答を生成します。

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUROUTER_API_KEY"],
    base_url="https://api.yourouter.ai/v1"
)

def get_current_weather(location, unit="celsius"):
    """Get the current weather in a given location"""
    if "boston" in location.lower():
        return json.dumps({"location": "Boston", "temperature": "10", "unit": unit})
    else:
        return json.dumps({"location": location, "temperature": "unknown"})

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location"]
            }
        }
    }
]

messages = [{"role": "user", "content": "What's the weather like in Boston, MA?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

response_message = response.choices[0].message
tool_calls = response_message.tool_calls

if tool_calls:
    available_functions = {
        "get_current_weather": get_current_weather,
    }
    messages.append(response_message)

    for tool_call in tool_calls:
        function_name = tool_call.function.name
        function_to_call = available_functions[function_name]
        function_args = json.loads(tool_call.function.arguments)

        function_response = function_to_call(
            location=function_args.get("location"),
            unit=function_args.get("unit"),
        )

        messages.append(
            {
                "tool_call_id": tool_call.id,
                "role": "tool",
                "name": function_name,
                "content": function_response,
            }
        )

    second_response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )

    final_response = second_response.choices[0].message.content
    print(final_response)

ビジョン（マルチモーダル）

多くのモデルはマルチモーダル入力に対応しており、リクエストに画像を含められます。画像説明、画像分析、視覚的な Q&A などに便利です。この機能は特定のプロバイダーだけのものではなく、gpt-4o、claude-3-5-sonnet-20240620、gemini-1.5-pro-latest などのモデルがビジョン機能を持っています。

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUROUTER_API_KEY"],
    base_url="https://api.yourouter.ai/v1"
)

def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode('utf-8')

image_path = "image.jpg"
base64_image = encode_image(image_path)

response = client.chat.completions.create(
    model="claude-3-5-sonnet-20240620",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What’s in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{base64_image}"
                    }
                }
            ]
        }
    ],
    max_tokens=300,
    extra_headers={"vendor": "anthropic"}
)

print(response.choices[0].message.content)

パラメータ（代表）

パラメータ	型	説明	既定値
`model`	string	使用するモデル ID。	必須
`messages`	array	これまでの会話を構成するメッセージ一覧。	必須
`max_tokens`	integer	chat completion で生成する最大トークン数。	`null`
`temperature`	number	使用するサンプリング温度。通常は 0 から 2 の範囲です。	`1`
`top_p`	number	temperature の代替となる nucleus sampling の指定。	`1`
`n`	integer	入力メッセージごとに生成する chat completion 候補数。	`1`
`stream`	boolean	設定すると、ChatGPT と同様に部分的な message delta を順次送信します。	`false`
`stop`	string or array	最大 4 つの停止シーケンス。API は該当箇所でそれ以上のトークン生成を停止します。	`null`
`presence_penalty`	number	-2.0 から 2.0 の値。正の値は、これまでのテキストに出現したかどうかに基づいて新しいトークンを抑制します。	`0`
`frequency_penalty`	number	-2.0 から 2.0 の値。正の値は、これまでのテキスト内での出現頻度に基づいて新しいトークンを抑制します。	`0`
`logit_bias`	map	指定したトークンが completion に出現する確率を調整します。	`null`
`user`	string	エンドユーザーを表す一意の識別子。監視や不正利用検知に役立ちます。	`null`
`tool_choice`	string or object	モデルがツールを使うか、どのように使うかを制御します。	`none`
`tools`	array	モデルが呼び出せるツールの一覧。	`null`

プロバイダー固有 API

統一 API に無いパラメータや挙動が必要な場合、上流のネイティブエンドポイントへ直接リクエストできます。この場合は vendor ヘッダーが必須です。

YouRouter は Authorization 以外のヘッダーとリクエストボディを可能な限りそのまま上流へ転送します。詳細はリクエスト転送を参照してください。

Gemini（Google）

Generate Content

Endpoint: POST /v1/projects/cognition/locations/us/publishers/google/models/{model}:generateContent

import os
import requests
import json

url = "https://api.yourouter.ai/v1/projects/cognition/locations/us/publishers/google/models/gemini-1.5-pro-latest:generateContent"

headers = {
    "Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}",
    "Content-Type": "application/json",
    "vendor": "google"
}

data = {
    "contents": [{
        "parts": [{"text": "Write a short story about a time-traveling historian."}]
    }]
}

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

print(json.dumps(response.json(), indent=2))

Safety Settings

リクエストに safetySettings オブジェクトを含めることで、コンテンツの安全性しきい値を設定できます。カテゴリとしきい値の完全な一覧は、公式の Google AI ドキュメントを参照してください。

import os
import requests
import json

url = "https://api.yourouter.ai/v1/projects/cognition/locations/us/publishers/google/models/gemini-pro:generateContent"

headers = {
    "Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}",
    "Content-Type": "application/json",
    "vendor": "google"
}

data = {
    "contents": [{"parts": [{"text": "Tell me a potentially controversial joke."}]}],
    "safetySettings": [
        {
            "category": "HARM_CATEGORY_HATE_SPEECH",
            "threshold": "BLOCK_LOW_AND_ABOVE"
        },
        {
            "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
            "threshold": "BLOCK_MEDIUM_AND_ABOVE"
        }
    ]
}

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

print(json.dumps(response.json(), indent=2))

Claude（Anthropic）

Messages API

Endpoint: POST /v1/messages

import os
import requests
import json

url = "https://api.yourouter.ai/v1/messages"

headers = {
    "Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}",
    "Content-Type": "application/json",
    "anthropic-version": "2023-06-01",
    "vendor": "anthropic"
}

data = {
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Explain the concept of neural networks to a 5-year-old."}
    ]
}

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

print(json.dumps(response.json(), indent=2))

Claude のツール利用

Claude にツールセットを渡すと、ユーザーのリクエストに答えるためにいつツールを使うべきかをモデルが判断します。この処理は複数ターンの会話で構成され、コード側でツールを実行し、その結果を Claude に返します。以下は、ツール利用のライフサイクル全体を示す完全な例です。

import os
import requests
import json

def get_weather(location):
    if "san francisco" in location.lower():
        return json.dumps({"location": "San Francisco", "temperature": "15°C", "forecast": "Cloudy"})
    else:
        return json.dumps({"location": location, "temperature": "unknown"})

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    }
]

messages = [{"role": "user", "content": "What is the weather like in San Francisco?"}]

initial_data = {
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": tools,
    "messages": messages
}

response = requests.post(
    "https://api.yourouter.ai/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}",
        "Content-Type": "application/json",
        "anthropic-version": "2023-06-01",
        "vendor": "anthropic"
    },
    json=initial_data
)

response_data = response.json()

if response_data.get("stop_reason") == "tool_use":
    tool_use_block = next(
        (block for block in response_data["content"] if block.get("type") == "tool_use"), None
    )

    if tool_use_block:
        tool_name = tool_use_block["name"]
        tool_input = tool_use_block["input"]
        tool_use_id = tool_use_block["id"]

        if tool_name == "get_weather":
            tool_result = get_weather(tool_input.get("location", ""))

            messages.append({"role": "assistant", "content": response_data["content"]})
            messages.append({
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": tool_use_id,
                        "content": tool_result,
                    }
                ],
            })

            final_data = {
                "model": "claude-3-opus-20240229",
                "max_tokens": 1024,
                "tools": tools,
                "messages": messages
            }

            final_response = requests.post(
                "https://api.yourouter.ai/v1/messages",
                headers={
                    "Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}",
                    "Content-Type": "application/json",
                    "anthropic-version": "2023-06-01",
                    "vendor": "anthropic"
                },
                json=final_data
            ).json()

            final_text = next(
                (block["text"] for block in final_response["content"] if block.get("type") == "text"),
                "No final text response found."
            )
            print(final_text)

ベストプラクティス

ルーティング：本番アプリケーションでは、高可用性のために auto ルーティングモードを使います。特定のモデルバージョンや機能が必要な場合は手動ルーティングを使います。詳細はルーティングを参照してください。
エラー処理：ネットワーク問題やプロバイダー障害は起こり得ます。特に長時間実行されるタスクでは、堅牢なエラー処理と指数バックオフ付きの再試行を実装してください。
UX のためのストリーミング：ユーザー向けアプリケーションでは、応答性の高いリアルタイム体験を提供するためにストリーミングを使います。
システムプロンプト：よく設計された system prompt は、モデルの振る舞い、口調、パーソナリティを導くうえで重要です。十分にテストし、継続的に改善してください。
トークン管理：入力コンテキストと出力生成の両方について、常にトークン上限を意識してください。API レスポンスの usage データを監視し、コストを追跡しながら予期しない切り詰めを避けます。

はじめに

モデル API

ルーティングと信頼性

API リファレンス

機能

法務

OpenAI 互換 API

基本的な使い方

高度な機能

マルチターン会話

ストリーミング

関数呼び出し / ツール利用

ビジョン（マルチモーダル）

パラメータ（代表）

プロバイダー固有 API

Gemini（Google）

Generate Content

Safety Settings

Claude（Anthropic）

Messages API

Claude のツール利用

ベストプラクティス

​OpenAI 互換 API

​基本的な使い方

​高度な機能

​マルチターン会話

​ストリーミング

​関数呼び出し / ツール利用

​ビジョン（マルチモーダル）

​パラメータ（代表）

​プロバイダー固有 API

​Gemini（Google）

​Generate Content

​Safety Settings

​Claude（Anthropic）

​Messages API

​Claude のツール利用

​ベストプラクティス

OpenAI 互換 API

基本的な使い方

高度な機能

マルチターン会話

ストリーミング

関数呼び出し / ツール利用

ビジョン（マルチモーダル）

パラメータ（代表）

プロバイダー固有 API

Gemini（Google）

Generate Content

Safety Settings

Claude（Anthropic）

Messages API

Claude のツール利用

ベストプラクティス