このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring AI 1.1.7 を使用してください！

チャットの使用 / 埋め込みレスポンスの使用

概要

Spring AI は、Usage インターフェースに getNativeUsage() メソッドを導入し、DefaultUsage 実装を提供することで、モデル使用状況の処理を強化しました。この変更により、フレームワーク全体の一貫性を維持しながら、さまざまな AI モデルが使用状況メトリクスを追跡・報告することが簡素化されます。

主な変更点

使用インターフェースの強化

Usage インターフェースに新しいメソッドが追加されました:

Object getNativeUsage();

このメソッドにより、モデル固有のネイティブ使用状況データにアクセスできるため、必要に応じてより詳細な使用状況追跡が可能になります。

ChatModel と併用

OpenAI の ChatModel を使用して使用状況を追跡する方法を示す完全な例を次に示します。

@SpringBootConfiguration
public class Configuration {

        @Bean
        public OpenAiChatModel openAiChatModel() {
            return OpenAiChatModel.builder()
                .options(OpenAiChatOptions.builder()
                    .apiKey(System.getenv("OPENAI_API_KEY"))
                    .build())
                .build();
        }

    }

@Service
public class ChatService {

    private final OpenAiChatModel chatModel;

    public ChatService(OpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    public void demonstrateUsage() {
        // Create a chat prompt
        Prompt prompt = new Prompt("What is the weather like today?");

        // Get the chat response
        ChatResponse response = this.chatModel.call(prompt);

        // Access the usage information
        Usage usage = response.getMetadata().getUsage();

        // Get standard usage metrics
        System.out.println("Prompt Tokens: " + usage.getPromptTokens());
        System.out.println("Completion Tokens: " + usage.getCompletionTokens());
        System.out.println("Total Tokens: " + usage.getTotalTokens());

        // Access native OpenAI usage data with detailed token information
        if (usage.getNativeUsage() instanceof com.openai.models.completions.CompletionUsage) {
            com.openai.models.completions.CompletionUsage nativeUsage =
                (com.openai.models.completions.CompletionUsage) usage.getNativeUsage();

            // Detailed prompt token information
            nativeUsage.promptTokensDetails().ifPresent(details -> {
                System.out.println("Prompt Tokens Details:");
                details.audioTokens().ifPresent(tokens -> System.out.println("- Audio Tokens: " + tokens));
                details.cachedTokens().ifPresent(tokens -> System.out.println("- Cached Tokens: " + tokens));
            });

            // Detailed completion token information
            nativeUsage.completionTokensDetails().ifPresent(details -> {
                System.out.println("Completion Tokens Details:");
                details.reasoningTokens().ifPresent(tokens -> System.out.println("- Reasoning Tokens: " + tokens));
                details.acceptedPredictionTokens().ifPresent(tokens -> System.out.println("- Accepted Prediction Tokens: " + tokens));
                details.audioTokens().ifPresent(tokens -> System.out.println("- Audio Tokens: " + tokens));
                details.rejectedPredictionTokens().ifPresent(tokens -> System.out.println("- Rejected Prediction Tokens: " + tokens));
            });
        }
    }
}

ChatClient と併用

ChatClient を使用している場合は、ChatResponse オブジェクトを使用して使用状況情報にアクセスできます。

// Create a chat prompt
Prompt prompt = new Prompt("What is the weather like today?");

// Create a chat client
ChatClient chatClient = ChatClient.create(chatModel);

// Get the chat response
ChatResponse response = chatClient.prompt(prompt)
        .call()
        .chatResponse();

// Access the usage information
Usage usage = response.getMetadata().getUsage();

プロンプトキャッシュ使用状況メトリクス

プロンプトキャッシュをサポートするプロバイダの場合、Usage インターフェースはプロバイダ固有の型変換を必要とせずにキャッシュメトリクスへの統一的なアクセスを提供します。

Usage usage = response.getMetadata().getUsage();

// Unified cache metrics — works across all providers
Long cacheReadTokens = usage.getCacheReadInputTokens();
Long cacheWriteTokens = usage.getCacheWriteInputTokens();

if (cacheReadTokens != null && cacheReadTokens > 0) {
    System.out.println("Cache hit: " + cacheReadTokens + " tokens read from cache");
}
if (cacheWriteTokens != null && cacheWriteTokens > 0) {
    System.out.println("Cache write: " + cacheWriteTokens + " tokens written to cache");
}

これらのメソッドは、プロンプトキャッシュをサポートしていないプロバイダに対して null を返します。

以下の表は、プロバイダ別のプロンプトキャッシュメトリクスの利用可能性を示しています。

プロバイダー キャッシュ読み取りトークン キャッシュ書き込みトークン

Anthropic

はい

はい (cacheCreationInputTokens)

AWS Bedrock

はい

はい

OpenAI

はい (cachedTokens)

いいえ

Google Gemini

はい (cachedContentTokenCount)

いいえ

DeepSeek

いいえ

いいえ

Mistral

いいえ

いいえ

Ollama

いいえ

いいえ

For detailed provider-specific cache metrics (such as per-modality cache breakdowns in Gemini), use getNativeUsage() to access the provider’s native usage object.

メリット

標準化 : さまざまな AI モデルの使用状況を一貫した方法で処理します。柔軟性 : ネイティブ使用状況機能簡素化を通じてモデル固有の使用状況データをサポートします: デフォルト実装拡張性で定型コードを削減: 互換性を維持しながら、特定のモデル要件に合わせて簡単に拡張できます

型安全性に関する考慮事項

ネイティブ使用状況データを扱うときは、型キャストを慎重に検討してください。

// Safe way to access native usage
if (usage.getNativeUsage() instanceof com.openai.models.completions.CompletionUsage) {
    com.openai.models.completions.CompletionUsage nativeUsage =
        (com.openai.models.completions.CompletionUsage) usage.getNativeUsage();
    // Work with native usage data
}