OpenAI SDK イメージ生成 (正式)

Spring AI は、OpenAI Java SDK を通じて OpenAI の DALL-E イメージ生成モデルをサポートし、Microsoft Foundry や GitHub モデルなどの OpenAI のサービスとの堅牢かつ公式にメンテナンスされた統合を提供します。

この実装は OpenAI の公式 OpenAI Java SDK [GitHub] (英語) を使用しています。Spring の代替 AI 実装については、OpenAI イメージの生成を参照してください。

DALL-E は、自然言語による記述からリアルなイメージやアートを作成できる、OpenAI の最先端のイメージ生成モデルです。

OpenAI SDK モジュールは、指定されたベース URL に基づいてサービスプロバイダー (OpenAI、Microsoft Foundry、または GitHub モデル) を自動的に検出します。

認証

認証はベース URL と API キーを使用して行われます。実装では、Spring Boot プロパティまたは環境変数を通じて柔軟な設定オプションが提供されます。

OpenAI の使用

OpenAI を直接使用している場合は、OpenAI サインアップページ (英語) でアカウントを作成し、API キーページ (英語) で API キーを生成します。

ベース URL はデフォルトで api.openai.com/v1 (英語) に設定されるため、設定する必要はありません。

spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url is optional, defaults to https://api.openai.com/v1

または環境変数を使用します:

export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL is optional, defaults to https://api.openai.com/v1

Microsoft Foundry の使用

Microsoft Foundry URL を使用すると、Microsoft Foundry が自動的に検出されます。以下のプロパティを使用して設定できます。

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.api-key=<your-api-key>
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>

または環境変数を使用します:

export OPENAI_BASE_URL=https://<your-deployment-url>.openai.azure.com
export OPENAI_API_KEY=<your-api-key>

パスワードレス認証（Azure に推奨）:

Microsoft Foundry は、API キーを提供せずにパスワードレス認証をサポートしており、Azure で実行する場合の安全性が高まります。

パスワードレス認証を有効にするには、com.azure:azure-identity 依存関係を追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

次に、API キーなしで設定します。

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# No api-key needed - will use Azure credentials from environment

GitHub モデルの使用

GitHub モデルのベース URL を使用すると、GitHub モデルが自動的に検出されます。models:read スコープで GitHub パーソナルアクセストークン（PAT）を作成する必要があります。

spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXX

または環境変数を使用します:

export OPENAI_BASE_URL=https://models.inference.ai.azure.com
export OPENAI_API_KEY=github_pat_XXXXXXXXXXX
API キーなどの機密情報を扱う際のセキュリティを強化するために、プロパティで Spring 式言語 (SpEL) を使用できます。
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}

リポジトリと BOM の追加

Spring AI アーティファクトは、Maven Central リポジトリと Spring スナップショットリポジトリに公開されています。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリセクションを参照してください。

依存関係の管理を支援するために、Spring AI は BOM (部品表) を提供し、一貫したバージョンの Spring AI がプロジェクト全体で使用されるようにします。Spring AI BOM をビルドシステムに追加するには、"依存関係管理" セクションを参照してください。

自動構成

Spring AI は、OpenAI SDK イメージモデル用の Spring Boot 自動構成を提供します。これを有効にするには、プロジェクトの Maven pom.xml または Gradle build.gradle ビルドファイルに以下の依存関係を追加してください。

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai-sdk'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。

プロパティの構成

接続プロパティ

プレフィックス spring.ai.openai-sdk は、OpenAI SDK クライアントを構成できるプロパティプレフィックスとして使用されます。

プロパティ 説明 デフォルト

spring.ai.openai-sdk.base-url

接続先の URL。設定されていない場合は、OPENAI_BASE_URL 環境変数から自動検出されます。

api.openai.com/v1 (英語)

spring.ai.openai-sdk.api-key

API キー。設定されていない場合は、OPENAI_API_KEY 環境変数から自動検出されます。

-

spring.ai.openai-sdk.organization-id

必要に応じて、API リクエストに使用する組織を指定します。

-

spring.ai.openai-sdk.timeout

リクエストのタイムアウト期間。

-

spring.ai.openai-sdk.max-retries

失敗したリクエストの最大再試行回数。

-

spring.ai.openai-sdk.proxy

OpenAI クライアント (Java Proxy オブジェクト) のプロキシ設定。

-

spring.ai.openai-sdk.custom-headers

リクエストに含めるカスタム HTTP ヘッダー。ヘッダー名とヘッダー値のマップ。

-

マイクロソフトファウンドリープロパティ

OpenAI SDK 実装は、自動構成による Microsoft Foundry のネイティブサポートを提供します。

プロパティ 説明 デフォルト

spring.ai.openai-sdk.microsoft-foundry

Microsoft Foundry モードを有効にします。ベース URL に openai.azure.com、cognitiveservices.azure.com、または .openai.microsoftFoundry.com が含まれている場合は自動検出されます。

false

spring.ai.openai-sdk.microsoft-deployment-name

Microsoft Foundry デプロイ名。指定されていない場合はモデル名が使用されます。エイリアス deployment-name でもアクセスできます。

-

spring.ai.openai-sdk.microsoft-foundry-service-version

Microsoft Foundry API サービスバージョン。

-

spring.ai.openai-sdk.credential

パスワードレス認証用の資格情報オブジェクト (com.azure:azure-identity 依存関係が必要)。

-

Microsoft Foundry はパスワードレス認証をサポートしています。com.azure:azure-identity 依存関係を追加すると、API キーが提供されていない場合、実装は自動的に環境から Azure の資格情報を使用しようとします。

GitHub モデルのプロパティ

GitHub モデルのネイティブサポートが利用可能です:

プロパティ 説明 デフォルト

spring.ai.openai-sdk.github-models

GitHub モデルモードを有効にします。ベース URL に models.github.ai または models.inference.ai.azure.com が含まれている場合は自動検出されます。

false

GitHub モデルには、models:read スコープの個人アクセストークンが必要です。OPENAI_API_KEY 環境変数または spring.ai.openai-sdk.api-key プロパティで設定してください。

イメージモデルのプロパティ

プレフィックス spring.ai.openai-sdk.image は、イメージモデルの実装を構成するためのプロパティプレフィックスです。

プロパティ 説明 デフォルト

spring.ai.openai-sdk.image.options.model

イメージ生成に使用するモデル。使用可能なモデル: dall-e-2、dall-e-3. 詳細については、モデル (英語) ページを参照してください。

dall-e-3

spring.ai.openai-sdk.image.options.n

生成するイメージの数。1 ～ 10 の範囲で指定する必要があります。dall-e-3 の場合、n=1 のみがサポートされます。

-

spring.ai.openai-sdk.image.options.quality

生成されるイメージの品質。hd は、より精細なディテールとイメージ全体の一貫性を備えたイメージを生成します。このパラメーターは dall-e-3 でのみサポートされます。使用可能な値: standard、hd。

-

spring.ai.openai-sdk.image.options.response-format

生成されたイメージが返される形式。url または b64_json のいずれかである必要があります。

-

spring.ai.openai-sdk.image.options.size

生成されるイメージのサイズ。dall-e-2 モデルの場合は、256x256、512x512、1024x1024 のいずれかである必要があります。dall-e-3 モデルの場合は、1024x1024、1792x1024、1024x1792 のいずれかである必要があります。

-

spring.ai.openai-sdk.image.options.width

生成されるイメージの幅。256, 512,, 1024 または dall-e-2 のいずれかである必要があります。

-

spring.ai.openai-sdk.image.options.height

生成されるイメージの高さ。256, 512,, 1024 または dall-e-2 のいずれかである必要があります。

-

spring.ai.openai-sdk.image.options.style

生成するイメージのスタイル。vivid または natural のいずれかにする必要があります。Vivid を指定すると、モデルはハイパーリアルでドラマチックなイメージを生成します。Natural を指定すると、より自然でハイパーリアルではないイメージを生成します。このパラメーターは dall-e-3 でのみサポートされます。

-

spring.ai.openai-sdk.image.options.user

エンドユーザーを表す一意の識別子。OpenAI が不正使用を監視および検出できます。

-

spring.ai.openai-sdk.image.options で始まるすべてのプロパティは、リクエスト固有のランタイムオプションを ImagePrompt 呼び出しに追加することによって実行時にオーバーライドできます。

ランタイムオプション

OpenAiSdkImageOptions.java [GitHub] (英語) は、使用するモデル、品質、サイズ、スタイル、生成するイメージの数などの OpenAI 構成を提供します。

デフォルトのオプションは、spring.ai.openai-sdk.image.options プロパティを使用して構成することもできます。

起動時には、OpenAiSdkImageModel コンストラクターを使用して、すべてのイメージ生成リクエストで使用されるデフォルトオプションを設定します。実行時には、ImagePrompt の一部として OpenAiSdkImageOptions インスタンスを使用することで、デフォルトオプションをオーバーライドできます。

たとえば、特定のリクエストのデフォルトのモデルと品質をオーバーライドするには、次のようにします。

ImageResponse response = imageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiSdkImageOptions.builder()
            .model("dall-e-3")
            .quality("hd")
            .N(1)
            .width(1024)
            .height(1024)
            .style("vivid")
        .build()));
モデル固有の OpenAiSdkImageOptions [GitHub] (英語) に加えて、ImageOptionsBuilder#builder() [GitHub] (英語) で作成されたポータブル ImageOptions [GitHub] (英語) インスタンスを使用できます。

サンプルコントローラー

新しい Spring Boot プロジェクトを作成し、spring-ai-openai-sdk を pom (または gradle) の依存関係に追加します。

src/main/resources ディレクトリに application.properties ファイルを追加して、OpenAI SDK イメージモデルを構成します。

spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.image.options.model=dall-e-3
api-key を OpenAI の資格情報に置き換えます。

これにより、クラスに注入できる OpenAiSdkImageModel 実装が作成されます。以下は、イメージモデルを使用するシンプルな @RestController クラスの例です。

@RestController
public class ImageController {

    private final ImageModel imageModel;

    @Autowired
    public ImageController(ImageModel imageModel) {
        this.imageModel = imageModel;
    }

    @GetMapping("/ai/image")
    public Map<String, Object> generateImage(
            @RequestParam(value = "prompt", defaultValue = "A light cream colored mini golden doodle") String prompt) {
        ImageResponse response = this.imageModel.call(
            new ImagePrompt(prompt,
                OpenAiSdkImageOptions.builder()
                    .quality("hd")
                    .N(1)
                    .width(1024)
                    .height(1024)
                .build()));

        String imageUrl = response.getResult().getOutput().getUrl();
        return Map.of("url", imageUrl);
    }
}

手動構成

OpenAiSdkImageModel [GitHub] (英語) は ImageModel を実装し、公式の OpenAI Java SDK を使用して OpenAI サービスに接続します。

Spring Boot の自動構成を使用していない場合は、OpenAI SDK イメージモデルを手動で構成できます。そのためには、プロジェクトの Maven pom.xml ファイルに spring-ai-openai-sdk の依存関係を追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-sdk</artifactId>
</dependency>

または、Gradle build.gradle ビルドファイルに次の内容を追加します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-sdk'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。
spring-ai-openai-sdk 依存関係は、OpenAiSdkChatModel および OpenAiSdkEmbeddingModel へのアクセスも提供します。OpenAiSdkChatModel の詳細については、OpenAI SDK チャットセクションを参照してください。

次に、OpenAiSdkImageModel インスタンスを作成し、それを使用してイメージを生成します。

var imageOptions = OpenAiSdkImageOptions.builder()
    .model("dall-e-3")
    .quality("hd")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

ImageResponse response = imageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiSdkImageOptions.builder()
            .N(1)
            .width(1024)
            .height(1024)
        .build()));

OpenAiSdkImageOptions は、イメージ生成リクエストの設定情報を提供します。オプションクラスは、オプションを簡単に作成できる builder() を提供します。

Microsoft Foundry 構成

Microsoft Foundry の場合:

var imageOptions = OpenAiSdkImageOptions.builder()
    .baseUrl("https://your-resource.openai.azure.com")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .deploymentName("dall-e-3")
    .azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
    .azure(true)  // Enables Microsoft Foundry mode
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);
Microsoft Foundry はパスワードレス認証をサポートしています。プロジェクトに com.azure:azure-identity 依存関係を追加してください。API キーを指定しない場合、実装は自動的に環境の Azure 認証情報を使用しようとします。

GitHub モデル構成

GitHub モデルの場合:

var imageOptions = OpenAiSdkImageOptions.builder()
    .baseUrl("https://models.inference.ai.azure.com")
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .model("dall-e-3")
    .githubModels(true)
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

可観測性

OpenAI SDK 実装は、Micrometer を介して Spring AI の可観測性機能をサポートします。すべてのイメージモデル操作は、監視とトレースのためにインストルメント化されています。

追加リソース