Box AIに質問する - Box Dev Docs

Box AI APIは、Business以上をご利用のすべてのお客様が利用できます。

Box AI APIを使用すると、指定した1ファイルまたは一連のファイルについて質問し、そのコンテンツに基づいた応答を得ることができます。たとえば、Boxでドキュメントを表示している場合に、Box AIに対して、コンテンツの要約を求めることができます。このほか、に質問することもできます。項目としてHubを渡した場合、Box AIはHub内のインデックスが作成されたコンテンツを検索し、厳選されたドキュメントに基づいた回答を返します。詳細については、を参照してください。

開始する前に

Platformアプリを作成して認証するには、に記載されている手順に従っていることを確認してください。

リクエストの送信

質問を含むリクエストを送信するには、POST /2.0/ai/askエンドポイントを使用し、必須のパラメータを指定します。

curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
         "mode": "single_item_qa",
         "prompt": "What is the value provided by public APIs based on this document?",
         "items": [
            {
            "type": "file",
            "id": "9842787262"
            }
         ],
         "dialogue_history": [
              {
              "prompt": "Make my email about public APIs sound more professional",
              "answer": "Here is the first draft of your professional email about public APIs",
              "created_at": "2013-12-12T10:53:43-08:00"
              }
          ],
          "include_citations": true,
          "ai_agent": {
            "type": "ai_agent_ask",
            "long_text": {
              "model": "openai__gpt_5_mini",
              "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
            },
            "basic_text": {
              "model": "openai__gpt_5_mini",
           }
         }
      }'

await client.ai.createAiAsk({
  mode: 'single_item_qa' as AiAskModeField,
  prompt: 'which direction sun rises',
  items: [
    {
      id: fileToAsk.id,
      type: 'file' as AiItemAskTypeField,
      content: 'Sun rises in the East',
    } satisfies AiItemAsk,
  ],
  aiAgent: aiAskAgentConfig,
} satisfies AiAsk);

client.ai.create_ai_ask(
    CreateAiAskMode.SINGLE_ITEM_QA,
    "which direction sun rises",
    [
        AiItemAsk(
            id=file_to_ask.id,
            type=AiItemAskTypeField.FILE,
            content="Sun rises in the East",
        )
    ],
    ai_agent=ai_ask_agent_config,
)

await client.Ai.CreateAiAskAsync(requestBody: new AiAsk(mode: AiAskModeField.SingleItemQa, prompt: "which direction sun rises", items: Array.AsReadOnly(new [] {new AiItemAsk(id: fileToAsk.Id, type: AiItemAskTypeField.File) { Content = "Sun rises in the East" }})));

try await client.ai.createAiAsk(requestBody: AiAsk(mode: AiAskModeField.singleItemQa, prompt: "which direction sun rises", items: [AiItemAsk(id: fileToAsk.id, type: AiItemAskTypeField.file, content: "Sun rises in the East")]))

client.getAi().createAiAsk(new AiAsk.Builder(AiAskModeField.SINGLE_ITEM_QA, "which direction sun rises", Arrays.asList(new AiItemAsk.Builder(fileToAsk.getId(), AiItemAskTypeField.FILE).content("Sun rises in the East").build())).aiAgent(aiAskAgentConfig).build())

BoxAIResponse response = BoxAI.sendAIRequest(
    api,
    "What is the content of the file?",
    Collections.singletonList("123456", BoxAIItem.Type.FILE),
    BoxAI.Mode.SINGLE_ITEM_QA
);

items = [{
    "id": "1582915952443",
    "type": "file",
    "content": "More information about public APIs"
}]
ai_agent = {
    'type': 'ai_agent_ask',
    'basic_text_multi': {
        'model': 'openai__gpt_3_5_turbo'
    }
}
answer = client.send_ai_question(
    items=items, 
    prompt="What is this file?",
    mode="single_item_qa",
    ai_agent=ai_agent
)
print(answer)

BoxAIResponse response = await client.BoxAIManager.SendAIQuestionAsync(
    new BoxAIAskRequest
    {
        Prompt = "What is the name of the file?",
        Items = new List<BoxAIAskItem>() { new BoxAIAskItem() { Id = "12345" } },
        Mode = AiAskMode.single_item_qa
    };
);

client.ai.ask(
    {
        prompt: 'What is the capital of France?',
        items: [
            {
                type: 'file',
                id: '12345'
            }
        ],
        mode: 'single_item_qa'
    })
    .then(response => {
        /* response -> {
            "answer": "Paris",
            "created_at": "2021-10-01T00:00:00Z",
            "completion_reason": "done"
        } */
    });

パラメータ

コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは太字で示されています。

パラメータ	説明	使用可能な値	例
`mode`	リクエストの種類。単一のファイルの場合は`single_item_qa`を使用します (`items`配列には要素が1つだけ含まれている必要があります)。複数のファイル (最大25ファイル) の場合は`multiple_item_qa`を使用します。ファイルサイズ、画像、プロンプトの制限に関する詳細については、を参照してください。	`single_item_qa`, `multiple_item_qa`	`single_item_qa`
`prompt`	ドキュメントまたはコンテンツに関する質問。最大10,000文字。		`What is this document about?`
`dialogue_history.prompt`	以前にクライアントによって提供され、大規模言語モデル (LLM) が回答したプロンプト。	`Make my email about public APIs sound more professional`
`dialogue_history.answer`	以前にLLMから提供された回答。	`Here is a draft of your professional email about public APIs.`
`dialogue_history.created_at`	プロンプトに対する前回の回答が作成された時点のISO日付形式のタイムスタンプ。	`2012-12-12T10:53:43-08:00`
`include_citations`	回答で引用情報を返すかどうかを指定します。	`true`, `false`	`true`
`items.id`	入力データとして指定するファイルまたはHubのID。		`112233445566`
`items.type`	指定する入力データの種類。単体または複数のファイルの場合には`file`を、Box Hubの場合には`hubs`を、それぞれ使用します。`hubs`を使用する場合には、リクエスト内でその項目が唯一の項目になっている必要があります。	`file`, `hubs`	`file`
`items.content`	項目のコンテンツ。通常はテキストレプリゼンテーションです。		`An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface...`
`ai_agent`	デフォルトのモデル構成を上書きします。これにより、モデル、プロンプトテンプレート、システムメッセージ、またはLLMパラメータを変更できます。仕組みについてはを参照してください。また、使用例についてはを参照してください。

ユースケース

項目について質問する

この例では、POST ask/ai APIを使用して1つ以上の項目について質問する方法を示します。このエンドポイントを使用する際は、指定する項目の数に応じて、忘れずにmodeパラメータを指定してください。

curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'

レスポンスは次のようになります。

{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview.\n2. If questions fall outside the scope of the document, Box AI will inform you that it cannot answer.\n3. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n4. Aim to stay within the scope of the document.\n5. Focus on text-based responses only.",
    "created_at": "2024-11-04T02:30:09.557-08:00",
    "completion_reason": "done"
}

Hubについて質問する

質問に際して個別のファイルを入力データとする代わりに、Box AIに対して特定の全体を指定すると、そのHubの厳選されたコンテンツに基づいた回答が得られます。この機能は、ファイルIDを自分で管理しなくとも、承認済みの資料に基づいた回答を自然言語で得ることができるため、RFP回答集、ポリシーライブラリ、製品ドキュメントポータルなどのナレッジベースに有用です。 Hubを対象とするクエリを実行する場合には、items.typeをhubs、items.idをHubのIDに、それぞれ設定します。この場合、リクエスト内に入力データとして含める項目は、Hubのみにする必要があります。以下の例では、single_item_qaモードを使用しています。これは、で紹介したパターンです。

curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "98765432",
            "type": "hubs"
        }
    ],
    "prompt": "What is our standard SLA for enterprise support?"
}'

Box AIは、インデックスが作成されているHubコンテンツを検索し、承認済みの資料に基づいて回答を返します。HubはBoxの権限を引き継いでいるため、Box AIはクエリを実行したユーザーがアクセス権限を持つドキュメントのみを参照します。Hubでは、AI機能が有効になっている必要があります (詳細については、を参照してください)。 Hubのプロビジョニング、Hubへのコンテンツ登録、Box AIを使用したクエリ実行の具体的な手順については、のチュートリアルを参照してください。

`content`パラメータを使用して質問する

Box AIへの入力のソースとしてcontentパラメータを使用すると、それがプライマリソースとして使用されます。

curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "12345678",
            "type": "file",
            "content": "This is a document about Box AI For documents. It consists of the functionality summary and guidelines on how to work with Box AI. Additionally, it provides a set of best practices for creating questions."
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'

このリクエストに対するレスポンスは、ファイルのコンテンツではなくcontentパラメータに基づきます。

{
    "answer": "The document does not provide specific guidelines on working with questions in Box AI for Documents. It only mentions that it includes a set of best practices for creating questions, but the details of those guidelines are not included in the text provided. If you have more information or another document, I can help further!",
    "created_at": "2024-11-04T02:31:51.125-08:00",
    "completion_reason": "done"
}

`citations`パラメータを使用して質問する

citationsパラメータをtrueに設定すると、レスポンスには、ソースファイルまたはBox AIが回答をまとめるのに使用したファイルからの抜粋が含まれます。

curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "multiple_item_qa",
    "include_citations": true,
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on working with responses in Box AI for Documents"
}'

その結果の回答には、ソースファイルとコンテンツの直接引用が含まれます。

{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview, and cannot answer questions outside its scope.\n2. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n3. Examples of better phrasing include asking for a numbered list of key points instead of just \"list key points,\" and requesting a succinct outline of important points rather than a general inquiry about the document's purpose.\n4. Stay within the scope of the document and focus on text-based responses only.",
    "created_at": "2024-11-04T02:35:00.578-08:00",
    "completion_reason": "done",
    "citations": [
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Guidelines for Box AI questions\nBox AI pulls information only from the document you loaded in preview."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "If you ask any questions outside of the scope of the document, Box AI informs you that it cannot answer the question with the information provided."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "As you ask Box AI to analyze your document, consider these suggestions:\n· Be as specific as possible."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Box AI for Documents\n\nWhen viewing a document in Box, you can ask Box AI to summarize document content, search key points, and write outline drafts based on your document files."
        }
    ]
}

​開始する前に

​リクエストの送信

​パラメータ

​ユースケース

​項目について質問する

​Hubについて質問する

​contentパラメータを使用して質問する

​citationsパラメータを使用して質問する

開始する前に

リクエストの送信

パラメータ

ユースケース

項目について質問する

Hubについて質問する

`content`パラメータを使用して質問する

`citations`パラメータを使用して質問する