After uploading files, you can perform intelligent Q&A with their content. This feature supports deep analysis and automated task processing for documents, images, audio, and video files. It offers three distinct processing modes to enable content understanding, information extraction, and intelligent Q&A across diverse file types—including documents, images, and audio/video—based on your specific use case.
Based on your specific use case, you can choose from the following three processing modes:
The File Q&A capability in Agent Applications operates through the following workflow:
This feature is available only in the China North 2 (Beijing) region.
(Not specified in original — left blank for future population)
The file Q&A behavior is determined by the Pre-parse Files toggle in the app's Planning section and the knowledge base association:
Click the upload icon next to the input box in the right-side test chat panel to upload a local file (valid within the session, up to 10 files, each no larger than 10MB), then ask questions about its content.
Example 1: Full-text understanding
Upload "Alibaba Cloud Bailian phone product introduction.docx" and ask: "Please summarize this file."
The assistant returns a summary: the document introduces six smartphone models under the Bailian, Tongyi, and Stardust brands, with a product overview table listing model, highlights, display, and storage/memory.
Example 2: Mixed retrieval with a knowledge base
First store a video file in the knowledge base, then upload test.mp4 via the upload icon and ask: "Does the person in this video appear in the knowledge base?"
The system performs knowledge retrieval and returns two results. After comparison, the assistant determines that the real person in the video does not match the anime-style illustration characters in the knowledge base and replies "the person in the video does not appear in the knowledge base".
When you select a Qwen VL series model and upload an image, you can configure how the image is processed:
File Q&A API calls follow the unified rate-limiting policy of the associated Agent Application.
For full API details, see: File Upload API.
| Processing Mode | Description | Best For | Characteristics |
|---|---|---|---|
| Full-Text Context Injection | The built-in parser extracts the entire file content and passes it (within model context-length limits) as a single context block to the model. | Tasks requiring global understanding—e.g., document summarization, full-text translation, or stylistic refinement. | Simple and direct—but constrained by the model’s context window length. |
| Chunk-Based Retrieval (RAG) | The built-in parser extracts file content and splits it into smaller chunks. During Q&A, the system retrieves the most relevant chunks from the file and feeds both the retrieved chunks and the user’s question to the model for response generation. | Long-document Q&A, knowledge-base retrieval, or scenarios where precise source attribution is required. | Handles ultra-long files effectively; answer quality depends on chunking strategy and retrieval performance. |
| Custom Processing | File metadata (e.g., URL or raw content) is passed to the model, enabling it to autonomously invoke external tools (e.g., plugins or MCPs) based on task requirements. | Advanced file operations—e.g., image style transfer, video content analysis followed by report generation. | Highly flexible and powerful—but relies on properly configured external tools (plugins, MCPs, etc.). |
How It Works
The File Q&A capability in Agent Applications operates through the following workflow:
- 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.
- Content Processing: Files are processed according to the app's file handling configuration (pre-parse toggle, knowledge base association). In retrieval scenarios, the parsed result is planned and retrieved together with the user intent and the knowledge base content. When Pre-parse Files is turned on, the parser extracts the file content and passes it to the agent for replies. Content that exceeds the limit is automatically truncated.
- 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.
- Documents:
.doc,.docx,.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
How to Use
The file Q&A behavior is determined by the Pre-parse Files toggle in the app's Planning section and the knowledge base association:
| Behavior | Configuration | How it works | Best for |
|---|---|---|---|
| Full-text understanding | Pre-parse Files ON | Uploaded documents, images, videos, and audio are parsed by the built-in parser; the extracted text is provided to the model, which answers based on the full file content | Document summarization, full-text translation, style polishing |
| Retrieval Q&A | Knowledge base associated | Uploaded files participate in retrieval together with knowledge base content; answers are generated from the most relevant recalled chunks | Long-document Q&A, pinpointing information sources |
| Custom processing | Pre-parse Files OFF | The file URL is passed through to the model, which handles it with the configured tools (plugins, MCP, etc.) | Image style transfer, video analysis, and other tool-involved tasks |
Configuration Steps
- Select a model in your Agent Application.
- Set the Pre-parse Files toggle in the Planning section as needed: ON parses file content for the model; OFF passes file URLs through.
- (Optional) To mix file and knowledge base Q&A, associate a knowledge base in the Knowledge Base module (see the Agent 2.0 or Agent 1.0 guides).
- (Optional, custom processing) Add the required tools (MCP, plugins, etc.) under Tools.
When Pre-parse Files is turned on, the parser extracts the file content and passes it to the agent for replies. Content that exceeds the limit is automatically truncated. For very long files, associate a knowledge base and use retrieval instead.
Upload a File and Chat
Click the upload icon next to the input box in the right-side test chat panel to upload a local file (valid within the session, up to 10 files, each no larger than 10MB), then ask questions about its content.
Example 1: Full-text understanding
Upload "Alibaba Cloud Bailian phone product introduction.docx" and ask: "Please summarize this file."
The assistant returns a summary: the document introduces six smartphone models under the Bailian, Tongyi, and Stardust brands, with a product overview table listing model, highlights, display, and storage/memory.
Example 2: Mixed retrieval with a knowledge base
First store a video file in the knowledge base, then upload test.mp4 via the upload icon and ask: "Does the person in this video appear in the knowledge base?"
The system performs knowledge retrieval and returns two results. After comparison, the assistant determines that the real person in the video does not match the anime-style illustration characters in the knowledge base and replies "the person in the video does not appear in the knowledge base".
Image Processing Configuration for Specific Models
When you select a Qwen VL series model and upload an image, you can configure how the image is processed:
- Model processing: the model analyzes the image with its own vision capability and answers directly, without calling external tools. Suitable for "look-and-answer" scenarios.
- Model processing + planning: after understanding the image, the model decides whether to call the configured external tools (such as plugins) for more complex tasks. Suitable for editing, transforming, or tool-assisted analysis.
- Select a Qwen VL series model and set the image processing mode to Model processing + planning.
- Add a portrait style-transfer tool under Tools.
MCP: bailian_image_style_repaint tool and converts the uploaded portrait into a vibrant cartoon-style image.
API Reference
Prerequisites
- Application Publishing: Ensure your application is published in the console before calling the API.
- Processing behavior: Files are processed exactly as configured in your Agent Application (pre-parse toggle, knowledge base association, etc.). The behavior cannot be changed dynamically at API call time.
Rate Limits
File Q&A API calls follow the unified rate-limiting policy of the associated Agent Application.
- Per application: default rate limit of 100 QPS (requests per second).
- Per account: default rate limit of 15,000 QPM (requests per minute), covering all API requests of all applications under the account, including file Q&A calls.
- Requests exceeding the limits are rejected with HTTP 429 and error code
Throttling.RateQuota, usually recovering within one minute; see Application Rate Limits. - 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
| Delivery Method | API Parameter | Primary Use / Characteristics |
|---|---|---|
Via image_list (image URLs) | image_list | For image search and visual understanding. Max file size: 10 MB. |
Via file_list (generic file URLs) | file_list | Passes generic file URLs. In Full-Text or Chunk-Based modes, system extracts and uses text content. In Custom Processing mode, model receives raw URL to invoke tools. Max file size: 10 MB. |
| Via File Upload API | parameters.session_file_ids | Recommended for production. Workflow: 1. Call the ApplyFileUploadLease and AddFile file upload APIs in turn to get a session file ID starting with file_session_. 2. Pass this ID via session_file_ids in the parameters object of the chat API request (sessionFileIds in the Java SDK). Supports larger files; more stable transmission. |
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?
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
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?
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_ids): Valid only within the current session; files expire after the session closes (up to 7 days at most), not for long-term storage. - URL-based (
image_list,file_list): Validity depends entirely on your provided URL’s lifetime and accessibility.
Why did my file upload fail?
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?
Why is the model’s response incomplete or inaccurate?
Common reasons:
- Content truncation: File content was cut off due to token limits. When Pre-parse Files is turned on, the parser extracts the file content and passes it to the agent for replies. Content that exceeds the limit is automatically truncated. For very long files, associate a knowledge base and use retrieval instead.
- 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?
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.