Skip to main content

OpenAI 互換ファイルインターフェイス

ファイルアップロードインターフェイスは、 Qwen-Long および Qwen-Doc-Turbo モデルを使用したドキュメント Q&A およびデータ抽出のためにファイルをアップロードするために使用されます。また、バッチタスクの入力ファイルをアップロードするためにも使用できます。

使用方法

ファイルインターフェイスは、Python または Java の OpenAI SDK を使用するか、HTTP API 呼び出しを行うことで呼び出すことができます。サポートされている操作には、ファイルのアップロード、クエリ、削除が含まれます。

前提条件

モデルの可用性

ファイル ID は、次のシナリオで使用できます:
  • Qwen-Long: 長文ドキュメントに対して Q&A を実行します。
  • Qwen-Doc-Turbo: ファイルからデータを抽出し、Q&A を実行します。
  • バッチ処理: バッチファイルをアップロードします。

使用方法

ファイルのアップロード

Model Studio ストレージスペースは、最大 10,000 ファイル、合計サイズ最大 100 GB をサポートします。ファイルに有効期限はありません。
  • ドキュメント分析用
  • バッチ処理用
purpose を file-extract に設定します。サポートされているファイル形式には、テキストファイル (TXT、DOCX、PDF、XLSX、EPUB、MOBI、MD、CSV、JSON など) と画像ファイル (BMP、PNG、JPG/JPEG、GIF、スキャンされた PDF など) が含まれます。単一ファイルの最大サイズは 150 MB です。
file_id を使用したドキュメント分析の詳細については、「ロングコンテキスト (Qwen-Long)」をご参照ください。

リクエストの例 

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # 環境変数を設定していない場合は、次の行を api_key="sk-xxx" に置き換え、Model Studio API キーを使用してください。
    # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーの取得: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# test.txt はローカルのサンプルファイルです。
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())

レスポンスの例 

{
    "id": "file-fe-xxx",
    "bytes": 2055,
    "created_at": 1729065448,
    "filename": "test.txt",
    "object": "file",
    "purpose": "file-extract",
    "status": "processed",
    "status_details": null
}

ファイル情報のクエリ

retrieve または GET メソッドで file_id を指定して、ファイル情報をクエリします。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

リクエストの例 

import os
from openai import OpenAI

client = OpenAI(
    # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーの取得: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file = client.files.retrieve(file_id="file-batch-xxx")

print(file.model_dump_json())

レスポンスの例 

{
  "id": "file-batch-xxx",
  "bytes": 27,
  "created_at": 1722480306,
  "filename": "test.txt",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "status_details": null
}

ファイルリストのクエリ

アップロードインターフェイスを介してアップロードされたファイルやバッチからの結果ファイルなど、すべてのファイルに関する情報を返します。
この操作は、より多くのフィルタリングパラメーターをサポートしています。詳細については、「パラメーターの説明」をご参照ください。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

リクエストの例 

import os
from openai import OpenAI

client = OpenAI(
    # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーの取得: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
     # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file_stk = client.files.list(after="file-batch-xxx",limit=20)
print(file_stk.model_dump_json())

レスポンスの例 

{
  "data": [
    {
      "id": "file-batch-xxx",
      "bytes": 27,
      "created_at": 1722480543,
      "filename": "test.txt",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    },
    {
      "id": "file-batch-yyy",
      "bytes": 431986,
      "created_at": 1718089390,
      "filename": "test.pdf",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    }
  ],
  "object": "list",
  "has_more": false
}

ファイルの削除

指定された file_id のファイルを削除します。ファイルリストのクエリ API を使用してファイル情報をクエリできます。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

リクエストの例 

import os
from openai import OpenAI

client = OpenAI(
    # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーの取得: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file_object = client.files.delete("file-batch-xxx")
print(file_object.model_dump_json())

レスポンスの例 

{
  "object": "file",
  "deleted": true,
  "id": "file-batch-xxx"
}

課金

ファイルのアップロード、ストレージ、クエリ操作は無料です。課金対象は、モデルを呼び出す際に使用される入力トークンと出力トークンのみです。

レート制限

ファイルアップロードインターフェイスの 1 秒あたりのクエリ数 (QPS) 制限は 3 です。ファイル情報のクエリ、ファイルリストのクエリ、およびファイル削除インターフェイスの合計 QPS 制限は 10 です。

本番稼働

  • 定期的なクリーンアップ: 10,000 ファイルの制限に達しないように、未使用のファイルを定期的に削除します。
  • ステータスチェック: ファイルをアップロードした後、そのステータスを確認します。status が processed の場合はアップロードが完了し参照可能であることを示しますが、解析が完了したことを意味するものではありません。解析完了前に呼び出すと File parsing in progress が返される場合があるため、しばらくしてから再試行してください。
  • レート制限の確認: ファイルアップロードインターフェイスの QPS 制限は 3 です。ファイル情報のクエリ、ファイルリストのクエリ、およびファイル削除インターフェイスの合計 QPS 制限は 10 です。
  • エラー処理: ネットワークエラー、API エラー、その他の問題に対する包括的な例外処理メカニズムを実装します。

よくある質問

1. アップロード後、ファイルステータスが「処理中」のままの場合はどうすればよいですか？

ファイルの処理には時間がかかりますが、通常は数秒で完了します。ステータスが長期間「処理中」のままである場合:
  • ファイル形式がサポートされているかどうかを確認します。
  • ファイルサイズが制限を超えていないか確認します。
  • retrieve API を使用して、ステータスを定期的にクエリします。

2. ファイル ID は異なるアカウント間で共有できますか？

いいえ、できません。ファイル ID は、それを生成した Alibaba Cloud アカウント内でのみ有効であり、アカウント間で共有することはできません。

3. アップロードされたファイルは永久に保存されますか？

はい、そうです。アップロードされたファイルは、削除しない限り、Alibaba Cloud アカウントに永久に保存されます。不要なファイルは定期的にクリーンアップしてください。

4. ファイルのアップロードが失敗する考えられる原因は何ですか？

  • API キーが無効であるか、エクスポートされていません。
  • ファイル形式がサポートされていません。
  • ファイルサイズが制限を超えています (file-extract: 150 MB、batch: 500 MB)。
  • ファイルの最大数 (10,000) または合計サイズ制限 (100 GB) に達しました。
  • ファイルアップロードインターフェイスの QPS 制限を超えました。制限は 3 QPS です。

5. purpose パラメーターには file-extract と batch のどちらを選択すべきですか？

  • file-extract: Qwen-Long または Qwen-Doc-Turbo を使用したドキュメント分析シナリオで使用します。
  • batch: バッチタスクで使用します。ファイルは、フォーマット要件を満たす JSONL ファイルである必要があります。

6. status が「processed」になった後も Qwen-Long でファイル解析中と表示される場合はどうすればよいですか？

status が processed であることは、ファイルのアップロードが完了し参照可能であることのみを示し、解析が完了したことを意味するものではありません。Qwen-Long の呼び出し時に File parsing in progress, please try again later. が返された場合は、しばらくしてから再試行し、ファイルの解析完了後に再度呼び出してください。

パラメーターの説明

カテゴリパラメータータイプ必須説明例
ファイルアップロードfileFileはいアップロードするファイル。Path("test.txt")
purposeStringはいアップロードされたファイルの目的を指定します。有効な値:file-extract: qwen-long モデルを使用したドキュメント理解用。batch: OpenAI 互換 - バッチジョブ用。ファイルはバッチファイルで指定されたフォーマットである必要があります。"file-extract"
ファイルクエリfile_idStringはいクエリするファイルの ID。"file-fe-xxx"
afterStringいいえファイルリストのクエリタスクでのページネーションに使用されるカーソル。after パラメーターの値は、現在のページの最後のアイテムの file_id です。これにより、データの次のページが取得されます。たとえば、クエリが 20 レコードを返し、最後の file_id が file-batch-xxx の場合、次のクエリで after="file-batch-xxx" を設定して、リストの次のページを取得します。"file-fe-xxx"
create_beforeStringいいえファイルリストのクエリタスクで、文字列形式のタイムスタンプ。指定された時間より前に作成されたファイル ID をフィルタリングして返します。"20250306123000"、"2025-11-12 10:10:10"、"2025-11-12"、"20251112"
create_afterStringいいえファイルリストのクエリタスクで、文字列形式のタイムスタンプ。指定された時間より後に作成されたファイル ID をフィルタリングして返します。"20250306123000"、"2025-11-12 10:10:10"、"2025-11-12"、"20251112"
purposeStringいいえファイルリストのクエリタスクで、目的別にファイルをフィルタリングします。指定された目的 (file-extract または batch) に一致するファイル ID のみを返します。"batch"
limitIntegerいいえファイルリストのクエリタスクで、クエリごとに返されるファイルの数。値の範囲は 1 から 2,000 で、デフォルト値は 2,000 です。2000
ファイル削除file_idStringはい削除するファイルの ID。"file-fe-xxx"
レスポンスパラメーター
共通のレスポンスパラメーターidString\ファイルの識別子。ファイルの削除タスクでは、これは正常に削除されたファイルの ID です。"file-fe-xxx"
bytesIntegerファイルのサイズ (バイト単位)。81067
created_atIntegerファイルが作成されたときの UNIX タイムスタンプ (秒単位)。1617981067
filenameStringアップロードされたファイルの名前。"text.txt"
objectStringオブジェクトタイプ。ファイルリストのクエリタスクの場合、値は常に "list" です。他のタスクでは、これは常に "file" です。"file"
purposeStringファイルの目的。有効な値は batch、file-extract、batch_output です。"file-extract"
statusStringファイルの現在のステータス。processed はアップロードが完了し参照可能であることを示しますが、解析が完了したことを意味するものではありません。"processed"
ファイルリストのクエリhas_moreBooleanデータの次のページがあるかどうかを示します。false
dataArray返されたファイルのリスト。リスト内の各要素のフォーマットは、共通のレスポンスパラメーターと一致します。
[{
 "id": "xxx",
 "bytes": 27,
 "created_at": 1722480543,
 "filename": "test.txt",
 "object": "file",
 "purpose": "batch",
 "status": "processed",
 "status_details": null
 }]
ファイルの削除deletedBoolean削除が成功したかどうかを示します。true の値は成功を示します。true

エラーコード

呼び出しが失敗した場合のトラブルシューティングについては、「エラーメッセージ」をご参照ください。