画像・音声・Embeddings — テキスト以外の入出力

これは何か

これまでの章で使ってきた POST /inference/v1/chat/completions(https://api.fireworks.ai 配下の絶対パス)は、テキストしか送れないわけではない。messages の content をテキストだけの文字列ではなく配列にして、テキストのブロックと並べて画像・動画・音声のブロックを追加するだけで、同じエンドポイント・同じ認証のまま多様な入力を扱える。埋め込み(embeddings)とリランキング(reranking)だけは別のエンドポイントで、それぞれ POST /inference/v1/embeddings と POST /inference/v1/rerank を使う。SDKに渡す base_url はこれらのパス末尾(/chat/completions 等)を除いた https://api.fireworks.ai/inference/v1 で、Authorization: Bearer $FIREWORKS_API_KEY とともに他の API と共通だ。

コンソール(app.fireworks.ai)側には、これらの機能の専用画面は用意されておらず、本章では API から扱う。Model Library でモデルを探すときに Vision などのフィルタを使う程度だ。

いつ使うのか

典型的なユースケースは4つある。画像の内容を読ませて説明文やOCR結果を得る(スクリーンショットの要約、書類の読み取り)。動画・音声の内容を理解させる(対応モデルは限られる)。自分のドキュメント群に対する意味検索の仕組み(RAG＝検索で見つけた文書を材料にLLMへ回答させる仕組み)の土台としてベクトルを作る。検索で拾った候補を精度良く並べ替える。それぞれ渡し方とServerlessでの対応範囲が違うので、最初にどれを使うか決めておく。

画像はVision系モデルなら常にServerlessで使えるわけではない。実際、Vision系モデルであってもServerless提供が終了することがある(例: Kimi K2.5は2026-06-26にServerlessから退役。詳細は後述)。

画像を渡す仕組み — image_url ブロック

content 配列に {"type": "text", ...} と並べて {"type": "image_url", "image_url": {"url": ...}} を追加する。リクエスト構造は OpenAI の vision API と同一なので、OpenAI 互換クライアントを使っていればコードはほぼそのまま動く。url フィールドが受け付ける値は3通りある。

{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
{"type": "image_url", "image_url": {"url": "mm_file://{file_id}"}}

1つ目は画像が公開URLにある場合にそのまま渡す方法。2つ目はローカルの画像をbase64エンコードしてdata URIにする方法(MIMEタイプのプレフィックスが必須)。3つ目はあらかじめアップロードして得た file_id を mm_file://{file_id} という形式で参照する方法だ。ただし2026-09時点で、このfile_idを取得するアップロード手順は公式ドキュメントに公開されていない(mm_file:// 形式そのものはAPIリファレンスのスキーマ記述で確認できる)。長い会話を繰り返すならURL参照の方がbase64よりレイテンシで有利、かつプロンプトキャッシュは画像部分にも効くため Time to First Token(最初のトークンが返るまでの時間)を最大80%短縮できる。

制約も明確に決まっている。1リクエストあたり画像は最大30枚(base64でもURLでも同じ)。base64エンコード後の合計サイズは10MB未満。URLを使う場合は1本あたり5MB未満かつ1.5秒以内にダウンロードが完了する必要がある。対応形式は .png .jpg .jpeg .gif .bmp .tiff .ppm の7種類。VLM(vision-language model＝画像も読めるモデル)はPDFをネイティブには受け付けないので、PDFを扱うには各ページを画像に変換してから渡す。

動画・音声を渡す仕組み

動画・音声は画像よりも対応モデルが限られる。2026-09時点でServerlessで動画入力に対応するのはGLM 5.3 Flashだけで、音声入力に対応するのはQwen3 Omniだけ(専用デプロイが必須)。Molmo2は動画専用で、動画内の音声は理解できない。

コンテンツブロックの型名は画像と対になっていて、動画は video_url、音声は audio_url。url の受け付け方は、動画は画像と同じくURL・base64・mm_file://{file_id} の3通り(音声は公式のコード例ではbase64のdata URIのみが使われている)。動画URLは、公式ドキュメントによればカスタム認可ヘッダを付けずに直接取得できる必要がある。

フレームサンプリングレートは fps パラメータで指定でき、値が高いほど動きに敏感になる代わりにトークン数が増える。有効範囲はモデルによって異なり、MiniMax M3 VLでは0.2〜5Hz(2026-09時点)。非M3の動画モデルでは同じ役割を sample_fps という名前(Kimi K2.5 VL由来のレガシー名)で指定する。本章で扱うGLM 5.3 Flashでの fps の対応可否・範囲は公式ドキュメントに明記が無いため、ここでは断定しない。MiniMax M3 VLは本章の動画対応モデル表(Serverless のGLM 5.3 Flashなど)とは別のモデルだが、fps の有効範囲がAPIリファレンスに明記されている唯一のモデルなので、書式そのものの例として以下に挙げる。

{"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4", "fps": 1}}

動画の前処理として「1 FPS・360p・先頭60秒・音声トラック除去」がffmpegの例として案内されているが、これはあくまで専用デプロイ向けのbase64サンプルで推奨されている値であって、APIのハード制限ではない。「60秒までしか渡せない」と早合点しないこと。むしろ、ffmpegで事前に1 FPSへ間引く代わりに、リクエストの fps パラメータで同じ効果を得られる場合がある。base64は合計10MB未満が前提なので、それを超えるサイズの動画はURL参照を使うか、アップロード済みファイルを mm_file://{file_id} で参照する。とくに50MBを超える動画はこの経路が公式に推奨されている(ただし、この file_id を取得するアップロード手順自体は2026-09時点で公式ドキュメントに公開されていない)。

埋め込みとは何か

埋め込み(embedding)とは、文章を「意味を表す数値の並び(ベクトル)」に変換したものだ。「猫はかわいい」と「犬はかわいい」のように意味が近い文章は、原点から見て似たような方向を向くベクトルになる。逆に「為替相場の予測」のように意味が離れた文章は違う方向を向く。この向きの近さ(角度)を測る指標としてよく使われるのがコサイン類似度で、これが意味検索(semantic search)の土台になる — クエリを同じ空間に埋め込み、向きの近い文章を探せば、キーワードが一致しなくても意味的に関連する文章を見つけられる。

Serverlessで使える埋め込みモデルの既定は fireworks/qwen3-embedding-8b。4B・0.6Bモデルは専用デプロイが必要になる。dimensions パラメータを渡すとベクトルの次元数(ベクトルの要素の個数。短くすると保存も検索も軽くなるが情報は落ちる)を短く指定できるが、これに対応する(resizable)のはQwen3系とレガシーの一部モデルのみで、非対応モデルに渡すと model: <id> is not resizable のエラーになる。重要な注意点として、Qwen3の埋め込みはL2正規化されていない — 単位ベクトル(ノルム=ベクトルの長さが1のベクトル)ではないので、内積をそのままコサイン類似度として使うと値がずれる(長さを揃えて初めて向きの近さと一致する)。リクエストに normalize: true を付ければAPI側でL2正規化された単位ベクトルが返るため、この手計算は不要になる(OpenAI SDKでは extra_body={"normalize": True} のように渡す)。レガシーのBERT系は多くが正規化済みだが、WhereIsAI/UAE-Large-V1 と mixedbread-ai/mxbai-embed-large-v1 の2つは例外的に未正規化だ。

レガシーのBERT系・sentence-transformers系(BAAI/bge-small-en-v1.5 など)はModel Libraryに掲載されていないが、HuggingFace形式のモデルIDをそのまま model に渡せばServerlessで動く(専用デプロイは不可)。fireworks/gpt-oss-120b のような生成用LLMも /inference/v1/embeddings に投げれば埋め込みとして使えるが、これは検索用に訓練された専用ヘッドではなく最終トークンのhidden stateを流用したものなので、検索精度が重要な場面では専用の埋め込みモデルを優先すべきだ。非対称検索(クエリとドキュメントを別々の方法で埋め込む)に強いVoyage AI系モデルも用意されているが、Serverless提供は無く常に専用デプロイになる。

検索パイプライン — embed から rerank まで

埋め込みとリランキングは組み合わせて使うのが定石だ。まずコーパス全体をあらかじめ埋め込んでおき、クエリが来たらベクトル検索で広く候補を集める(再現率＝拾うべき候補をどれだけ取りこぼさないかの指標を重視。計算コストは低い)。次にリランカーがその候補だけを精密に並べ替える(精度重視、1件あたりの計算コストは高いので対象を絞ってから使う)。全件をリランカーに通さず、まず安いベクトル検索で絞り込んでから高いリランカーにかける、という役割分担がポイントだ。

実装は2通りある。POST /inference/v1/rerank は query と documents を渡すだけの簡便なエンドポイントで、返り値の data は relevance_score(0〜1)の降順で並んでいる。ただし対応モデル・並列オプションが限られる。より柔軟に制御したいなら POST /inference/v1/embeddings に return_logits を渡す方式を使う。Qwen3 Rerankerは「クエリとドキュメントの組が関連するか」をyes/noで答えるように訓練されたモデルで、この方式では呼び出し側が <Instruct>: 指示・<Query>: クエリ・<Document>: ドキュメント の3行を改行で連結した文字列に整形して input に渡し、return_logits に"yes"/"no"に対応するトークンID(Qwen3トークナイザで確認できる値。2026-09時点で"no"=2753、"yes"=9454)を指定する。返ってくる確率は return_logits に並べたトークンIDと同じ順で並ぶので、[no, yes]の順(no=2753、yes=9454)で渡したなら2番目の値が関連度スコアになる。normalize: true を付けるとその2つのロジット(モデルが各トークンに与える生のスコア)にソフトマックス(スコアの組を合計1の確率に変換する計算)がかかり、"yes"の確率がそのまま関連度スコアになる。どちらの方式でも、Serverlessで使えるリランカーは qwen3-reranker-8b のみだ。

ハンズオン

curl https://api.fireworks.ai/inference/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FIREWORKS_API_KEY" \
  -d '{
    "model": "accounts/fireworks/models/glm-5p3-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "この画像を日本語で説明してください"},
          {
            "type": "image_url",
            "image_url": {
              "url": "https://images.unsplash.com/photo-1582538885592-e70a5d7ab3d3?w=800"
            }
          }
        ]
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("FIREWORKS_API_KEY"),
    base_url="https://api.fireworks.ai/inference/v1",
)

sentences = ["猫はとてもかわいい動物です", "犬はとても愛らしい動物です"]

resp = client.embeddings.create(
    model="fireworks/qwen3-embedding-8b",
    input=sentences,
)

def cosine_similarity(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    norm_a = sum(x * x for x in a) ** 0.5
    norm_b = sum(y * y for y in b) ** 0.5
    return dot / (norm_a * norm_b)

vec_a = resp.data[0].embedding
vec_b = resp.data[1].embedding
print(cosine_similarity(vec_a, vec_b))

curl https://api.fireworks.ai/inference/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FIREWORKS_API_KEY" \
  -d '{
    "model": "fireworks/qwen3-reranker-8b",
    "query": "フランスの首都は？",
    "documents": [
      "パリはフランスの首都であり、エッフェル塔やルーヴル美術館がある最大都市です。",
      "フランスはワインや料理、豊かな歴史で知られる西ヨーロッパの国です。",
      "ヨーロッパの天気は北部と南部で大きく異なります。"
    ],
    "top_n": 2,
    "return_documents": true
  }'

つまずきポイント

理解度チェック

まとめ

• 画像・動画・音声は、チャット用の同じエンドポイントに専用のコンテンツブロックを追加するだけで渡せる。
• 渡し方は画像・動画ならURL・base64・mm_file:// によるファイル参照の3通りで、ファイルサイズに応じて使い分ける(音声は公式のコード例ではbase64のみ)。動画が50MB超のときは mm_file:// が公式推奨(file_idの取得手順自体は2026-09時点で非公開)。
• 埋め込みは文章をベクトル化する技術で、意味が近い文章は空間上で近くなる。検索の土台になる。Qwen3の埋め込みは正規化されていない点に注意する。
• 大規模な候補集合はベクトル検索で広く集め、少数の候補だけをリランカーで精密に並べ替える2段構えが定石。

次章(第7章)では、Tool Calling・Structured Outputs・プロンプトキャッシュなど、開発を助けるAPI機能を扱う。

参考リンク

• Query vision-language models
• Video & audio inputs
• Generate embeddings and rerank results
• API Reference: Create Chat Completion
• API Reference: Create embeddings
• API Reference: Rerank documents
• Serverless Pricing
• Fireworks AI Pricing