操作ガイド

[更新: 2025年09月24日]

提供モデルとAPIドキュメント

さくらのAI Engine が提供しているモデル

さくらのAI Engine が対応しているモデルは以下の通りです。

チャットモデル：
- Qwen3-Coder-30B-A3B-Instruct
- Qwen3-Coder-480B-A35B-Instruct-FP8
- gpt-oss-120b
- llm-jp-3.1-8x13b-instruct4
埋め込みモデル：
- multilingual-e5-large
音声の文字起こしモデル：
- whisper-large-v3-turbo

チャットモデルは、上記サンプルと同じコマンドのモデル名のみを変更してご利用ください。

実際に利用できるモデルは、コントロールパネルの左メニューから 利用可能なモデル を選択することで確認できます。

API ドキュメント

APIのドキュメントは以下の通りです。

チャット補完・音声文字起こし用API、およびドキュメント・RAG APIでは、「アカウントトークンの発行」で発行したトークンを利用します。

ドキュメント・RAG API の使い方

さくらのAI Engine では、ホスティングしているLLMモデル用APIとは別に、RAGのためのAPIとベクトルストアを提供しています。

ドキュメント・RAG API の概要

Retrieval-Augmented Generation（RAG）とは、大規模言語モデル（LLM）が外部の知識ベースやドキュメントを検索（Retrieval）し、その検索結果を入力として取り込みながら応答を生成（Generation）する手法です。これによりLLMは本来知りえない企業内部のドキュメントや最新のニュースなどを回答することができます。

RAGの仕組みや処理フローはさくらのナレッジの記事を参考にしてください。

RAGの構築においては、あらかじめ与えられ外部の知識をベクトル化して、専用ベクトルストアに格納する処理や、検索時に投入される質問をベクトル化して、ベクトルストアに検索を行う処理などの実装が必要となりますが、さくらのAI Engine ではそれらを実装することなくAPI呼び出しだけでRAGを構築できます。

さくらのAI Engine では、事前に登録したドキュメントをベクトル化してベクトルストアに格納しておき、質問に対してベクトルストアから検索し、指定したLLMモデルで自然な言語に変換するまでを一つのAPIコールで実行できます。

2種類のAPIを提供

ドキュメントを参照するAPIとして、次の2種類のAPIを用意しています。

documents_query：ベクトルストアに対する自然言語の検索を実行します。回答はベクトルストアに保存されているドキュメントまたはその一部であるチャンクがそのまま出力されます。
documents_chat：ベクトルストアに対する自然言語の検索を実行し、検索結果を利用して回答を生成します。回答は指定したLLMモデルにより自然な言語で生成されます。

通常RAGにおけるチャット補完では documents_chat を使って、1.投入された質問をベクトル化 2.ベクトルストアへの検索 3.検索結果を指定したLLMモデルで自然な言語に変換という3つのステップで行われますが、さくらのAI Engine はこれを一つのAPIコールで処理します。

RAGのAPIの利用においては、埋め込みモデルおよびチャットモデルの利用料金が発生します。

ドキュメント補完時のチャンクの仕様

さくらのAI Engine にドキュメントを取り込む際に、およそ512文字単位で分割してベクトル化して格納されます。この分割された単位をチャンクと呼びます。検索はチャンク単位で行われ、検索結果として複数のチャンクが返される場合があります。

RAGのクイックスタート

ここでは例としてPDFを検索対象にし、RAGを試します。取り込んだPDFに対する単純な全文検索ではなく、LLMを活用してベクトル検索と自然な回答を生成します。

文章の取り込みは一般的なドキュメントフォーマット (txt,pdf,html,docx,xlsx,mdなど) に対応しています。

1. ドキュメントのベクトル化とベクトルストアへの保存

一般的に埋め込みと呼ばれる作業です。適当なテスト用PDFを用意して以下のコマンドを実行します。 <Token> は利用手順で取得したアカウントトークンに置き換えてください。 <uuid:シークレット> 形式のまま置き換えて実行します。

ドキュメントの保管には料金が発生します。基盤モデル無償プランの場合においても、ドキュメントの保管には料金が発生しますのでご注意ください。また、ドキュメントのベクトル化の際にはembeddingsモデルの利用料金が発生します。

curl --request POST \
 --url https://api.ai.sakura.ad.jp/v1/documents/upload/ \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <Token>' \
 --header 'Content-Type: multipart/form-data' \
 --form "file=@test.pdf"

以下のようなレスポンスが戻ります。

{"id":"f9ccb16f-b231-45d6-a7db-7cdcd077638a","status":"pending","content":"","name":"test.pdf","tags":[],"model":"multilingual-e5-large"}

しばらく待ってコンソール左メニューでドキュメントを選択すると、ドキュメントの取り込みが完了しています。

ドキュメントのベクトル化においては、アップロードされたファイル（PDF・テキストファイルなど）から自動的に文章を抽出し、検索や回答に利用します。ただし、ファイル形式や状態によっては、正しく文章が取り込めない場合があります。

特に以下のような場合には、正確に解析できないことがあります。

画像として保存されたPDF（スキャンデータなど）
特殊なフォントやレイアウト（縦書き、段組み、数式や図表を多用したもの）
暗号化やパスワード保護されたファイル
非対応のファイル形式や破損したファイル

万一、正しく取り込めない場合は、以下をお試しください。

ファイル形式を変えて再度アップロードする
アップロードするファイルの状態を確認する（破損していないか、正しい形式かなど）
事前にテキストファイルに変換してからアップロードする

本サービスは、すべてのファイルの内容を完全に取り込めることを保証するものではありません。

2. コントロールパネルからの検索の実行

質問したい内容を入力して クエリ実行 すると、結果が出力されます。ここでは. documents_chat を使って、質問に対する自然な回答を生成します。

3. API経由のでのRAG実行

以下のコマンドを実行します。

curl --request POST \
  --url https://api.ai.sakura.ad.jp/v1/documents/chat/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer c978bda0-2949-409d-a669-8d7fcd921963:YhK0IW+huu8U1kBwzOqzoaInmoe2M4UIblUKoFMc' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "multilingual-e5-large",
    "chat_model": "gpt-oss-120b",
    "query": "質問文",
    "top_k": 3,
    "threshold": 0.3
  }'

音声の文字起こし用APIの使い方

さくらのAI Engine では、Whisperとういうモデルをホスティングしており、音声を文字起こしできます。会議やインタビューの議事録などの書き起こしに利用できます。

音声の文字起こしのクイックスタート

以下は、MP3を検索対象として音声を文字起こすサンプルです。

1. 音声ファイルの文字起こしリクエスト

API同期型で動作するため、音声ファイルは30分、もしくは30MBの制限があります。

次のコマンドを実行します。 <Token> は利用手順で取得したアカウントトークンに置き換えてください。 <uuid:シークレット> 形式のまま置き換えて実行します。

curl --request POST \
  --url https://api.ai.sakura.ad.jp/v1/audio/transcriptions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@sample.mp3' \
  --form 'model=whisper-large-v3-turbo'

以下の様なレスポンスが戻ります。

{"text":"こんにちは。皆さん聞こえますか","model":"whisper-large-v3-turbo"}

一般的な音声ファイルフォーマット (mp3,wav等) に対応しています。ただし、すべての音声形式に対応しているわけではなく、ファイルの状態によっては正しく文字起こしできない場合があります。

正しく処理できない場合は、以下をお試しください。

音声ファイルの形式を変えて再度アップロードする
アップロードする音声ファイルの状態を確認する（破損していないか、正しい形式かなど）
モノラル音声に変換してからアップロードする

本サービスは、すべての音声ファイルの内容を完全に文字起こしできることを保証するものではありません。

解約および解約時のRAGデータの取り扱い

RAGにアップロードしたドキュメント以外に、データは保管されていません。解約の際はすべてのドキュメントの削除をお願いします。すべてのドキュメントを削除しないと解約できませんのでご注意ください。

解約手順は、次のとおりです。

1. ドキュメント削除

コントロールパネルのドキュメント詳細画面から 削除する をクリックします。

削除は、API経由でも実行できます。詳しくはAPIドキュメントをご覧ください。

2. アカウントトークンの削除

コントロールパネルの左メニューからアカウントトークンを選択して、トークンを削除します。

3. 解約の操作

プラン選択画面にて 解約はこちら をクリックしてから、プラン解約画面にて プランを解約する をクリックします。