File Q&A

Based on your specific use case, you can choose from the following three processing modes:

​

How It Works

The File Q&A capability in Agent Applications operates through the following workflow:

1. File Parsing: The system automatically detects and parses uploaded files—including documents, images, audio, and video—extracting text, visual, or audio information. The built-in parser focuses exclusively on extracting plain-text content from supported file formats.
2. Content Processing: Based on the processing mode selected in the application configuration, parsed content is handled accordingly.
   • Chunking Strategy: In Chunk-Based Retrieval mode, text is split by token count (with configurable overlap to preserve semantic continuity). Chunk size can be adjusted in the application settings.
3. Intelligent Q&A: The large language model synthesizes answers using both the file content and the user’s question—delivering accurate, context-aware responses.

​

Supported Scope

​

Supported Region

This feature is available only in the China North 2 (Beijing) region.

​

Supported Models

(Not specified in original — left blank for future population)

​

Supported File Formats

• Up to 10 files may be uploaded per session.
• Each file must be ≤10 MB.
• Uploaded files persist only within the current session. Refreshing or closing the page will cause them to be lost—complete required actions promptly.

Supported local file types:

• Documents: .doc, .docx, .wps, .ppt, .pptx, .xls, .xlsx, .md, .txt, .pdf
• Images: .png, .jpg, .jpeg, .bmp, .gif
• Video: .mp4, .mkv, .avi, .mov, .wmv, .webm, .flv
• Audio: .aac, .amr, .flac, .m4a, .mp3, .mpeg, .ogg, .opus, .wav, .wma

For files >10 MB, we recommend using the File Upload API, described later in this document.

​

How to Use

​

Full-Text Context Injection

Usage Steps

• Select a model in your Agent Application.
• In the module, choose Full-Text Context Injection.
• In the right-side debug panel, click the upload icon (📁) next to the input box to upload a local file—then ask questions about its content.

Parameter Configuration Click to enter the configuration page:

• Max Tokens Per File: Limits the number of tokens extracted from a single file. Excess content is truncated from the end.
• Max Assembled Tokens: Limits total tokens across all uploaded files after concatenation. Excess is truncated from the end of the last appended file.

When enabled, Full-Text Context Injection delivers parsed file content directly to the agent—and automatically truncates oversized content. To avoid information loss, set these parameters thoughtfully—or consider switching to Chunk-Based Retrieval for long files. Example Upload Alibaba Cloud Bailian Smartphone Product Introduction.docx, then ask:

“Please summarize the content of this file.”

The AI assistant returns:

“This document introduces six smartphone models under the Bailian, Tongyi, and Xingchen brands. A summary table lists each model’s key specs—including screen size/resolution/refresh rate, storage, and RAM. Examples:

• Bailian X1: 6.7″, 1440×3200 @ 120Hz, 256GB + 12GB RAM
• Tongyi Vivid 7: 6.5″, 1080×2400, 128GB + 8GB RAM
• Xingchen S9 Pro: 6.9″ with under-display camera, 512GB + 16GB RAM”

---

​

Chunk-Based Retrieval

Parameter Configuration Click to enter the configuration page:

• Max Retrieved Chunks: Maximum number of text chunks referenced in the model’s response.
• Max Assembled Chunk Tokens: Total token limit for concatenated retrieved chunks. If exceeded, lowest-scoring chunks are dropped first until the limit is satisfied.
• Valid range:
  • Max Retrieved Chunks: 1–20
  • Max Assembled Chunk Tokens: 1–98,304

Below the config panel, select a retrieval mode:

• Enable Chunk-Based Retrieval: System performs complex intent-aware planning and retrieval using both query and knowledge base.
• Custom Processing Mode: Agent autonomously plans and invokes tools.

Retrieval from Uploaded Files Only Usage Steps

• Select a model in your Agent Application.
• In the module, choose Chunk-Based Retrieval.
• In the right-side debug panel, click the upload icon (📁) to upload a local file—then ask questions about its content.

Example Upload Alibaba Cloud Bailian Smartphone Product Introduction.docx, then ask:

“Please recommend a smartphone around ¥5,000.”

The system retrieves 4 relevant chunks (relevance scores: 0.99, 0.47, 0.46, 0.44) from the uploaded file. The AI generates a recommendation like:

“Bailian X1 — priced at ¥4,599–¥4,999. Key highlights: high-refresh display, flagship performance, all-day battery life, and professional-grade imaging.”

Hybrid Retrieval: Files + Knowledge Base Usage Steps

• Select a model in your Agent Application.
• In the module, choose Chunk-Based Retrieval.
• In the same module, click + and select an existing knowledge base (create one first if none exists).
• In the right-side debug panel, click the upload icon (📁) to upload a local file—then ask questions leveraging both the uploaded file and the linked knowledge base.

Example

• First, store a video file in your knowledge base.
• Then, upload test.mp4 via the input box and ask:

“Does any person in this video appear in the knowledge base?”

The system retrieves two results:

• [Document Library] (316 chars, score 0.25)
• [File Processing] (1771 chars, score 0.99)

The AI compares visual features and concludes:

“The person in the video—a young man dancing in a black shirt and white trousers—does not match any anime-style illustrations in the knowledge base. Therefore, no match was found.”

---

​

Custom Processing

Usage Steps

• Select a model in your Agent Application.
• In the module, choose Custom Processing.
• Under Tools, add required tools (MCPs, plugins, etc.).
• In the right-side debug panel, click the upload icon (📁) to upload a file—then issue instructions via chat to trigger tool invocation.

Special Image Processing Configuration for Qwen-VL Models When using Qwen-VL series models and uploading images, click the gear icon (⚙️) to configure processing behavior. In Custom Processing mode, file handling logic varies by type:

• Images: Two options:
  • Model-Only Processing: The model uses its native vision capabilities to analyze and answer—no external tools invoked. Ideal for “visual Q&A.”
  • Model + Planning: After visual understanding, the model decides whether to call configured external tools (e.g., plugins) for advanced tasks—e.g., editing, style transfer, or analytical augmentation.
  Click the gear icon next to Custom Processing to select either option.
• Other Files (Documents, Audio/Video): The model autonomously determines whether tool invocation is needed.

Example Agent Configuration:

• Select Qwen-VL model.
• Click the gear icon next to Custom Processing, and set image handling to Model + Planning.
• Add the Character Style Repainting tool under Tools.

Usage:
Upload girl.png, then ask:

“Convert this image’s artistic style to vibrant cartoon.”

The agent invokes MCP: bailian_image_style_repaint, successfully transforming the portrait into a vibrant cartoon style.

​

API Reference

​

Prerequisites

• Application Publishing: Ensure your application is published in the console before calling the API.
• Processing Mode: Files are processed exactly as configured in your Agent Application (e.g., Full-Text Context Injection or Chunk-Based Retrieval). Mode cannot be dynamically changed at API call time.

​

Rate Limits

File Q&A API calls follow the unified rate-limiting policy of the associated Agent Application.

• Default Limit: 100 calls per minute per Agent Application.
• Shared Quota: This limit applies to all API requests to the application—including File Q&A, chat, and other endpoints.
  • Example: If you make 50 File Q&A calls in one minute, only 50 remaining calls are available for other APIs.

​

File Delivery Methods & Parameters

For full API details, see: File Upload API.

​

Billing

• File Upload: No charge for uploading files.
• Model Invocation: Q&A over file content consumes input/output tokens billed at standard model rates. See Pricing. Token usage varies by mode:
  • Full-Text Context Injection: Entire (or truncated) file content is passed as input → higher input token cost.
  • Chunk-Based Retrieval: Only user query + top-retrieved chunks are passed → significantly lower input token cost; ideal for long documents.
  • Custom Processing: Token cost depends on interaction complexity—e.g., instruction parsing, tool invocation, result summarization.
• Tool Invocation: Some tools incur separate fees—see pricing details on each tool’s documentation page.

​

Frequently Asked Questions

How do I provide a publicly accessible file URL for the API?
We recommend Alibaba Cloud Object Storage Service (OSS)—it provides highly available, reliable storage and easy public URL generation.
Ensure your URL is reachable by Alibaba Cloud Bailian services: test it in a browser or via curl. How long do uploaded files remain valid?

• Chat UI upload: Valid only for the current session—expires on page refresh, close, or session timeout.
• File Upload API (session_file_id): Typically valid for 24 hours.
• URL-based (image_list, file_list): Validity depends entirely on your provided URL’s lifetime and accessibility.

Why did my file upload fail?
Possible causes include:

• File issues: Check size and format compliance.
• Network issues: Verify connectivity to Bailian service endpoints.
• URL issues: Confirm public accessibility and avoid temporary signed URLs.
• API issues: Validate authentication headers and parameter formatting.
• Error messages: Always inspect the API response body—it usually pinpoints the root cause.

Why is the model’s response incomplete or inaccurate?
Common reasons:

• Content truncation: In Full-Text mode, increase Max Tokens Per File and Max Assembled Tokens, or switch to Chunk-Based Retrieval.
• Vague queries: Be specific—e.g., instead of “Tell me about this,” try “List all product SKUs and their screen sizes.”
• Poor retrieval (Chunk-Based mode): May stem from low-relevance chunks or suboptimal chunking. Try refining your query for better intent alignment—or adjust chunk size in app settings.
• Low-quality source files: Scanned PDFs with poor resolution, complex tables/formulas, or malformed encodings hinder parsing. Prefer clean, well-structured originals.

Why does my sub-business space show “Unauthorized” when selecting a model in Agent Applications?
Sub-business spaces require explicit authorization from the parent business space for specific models. Refer to the Sub-Business Space Model Authorization Guide.