After uploading files in an Agent Application , you can ask intelligent questions about their content. This feature supports content understanding, information extraction, and intelligent Q&A for documents, images, audio, and video files, offering three processing modes. Choose the mode that best fits your needs:
| Processing Mode | Description | Best For | Characteristics |
|---|---|---|---|
| Full-text citation | An internal parser extracts the file content. The full content—within the model's context length limit—is passed to the model as a single input. | Tasks requiring global understanding, such as document summarization, full-text translation, or style refinement. | Simple and direct, but limited by the model's context length. |
| Chunked retrieval (RAG) | An internal parser extracts the file content and splits it into smaller chunks. When you ask a question, the system retrieves the most relevant chunks and passes them—and your question—to the model to generate an answer. | Long-document Q&A, knowledge base search, or scenarios where precise source attribution is required. | Handles very long files. Answer quality depends on chunking and retrieval strategy. |
| Custom processing | You provide the file (as a URL or raw content) to the model. The model then decides whether to call external tools—such as plugins or MCP Server—to process the file based on the task requirements. | Tasks requiring additional file operations, such as image style transfer or generating reports after video analysis. | Powerful and flexible, and depends on the configured tools (such as plugins and MCP). |
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: Based on the processing mode selected in the application configuration, parsed content is handled accordingly.
- Chunking Strategy: In Chunked retrieval mode, text is split by token count (with configurable overlap to preserve semantic continuity). Chunk size can be adjusted in the application settings.
- Intelligent Q&A: The large language model synthesizes answers using both the file content and the user's question—delivering accurate, context-aware responses.
Scope
Supported regions
This documentation applies only to the China (Beijing) region.
Supported models
Data may be delayed. For the latest supported models, check your agent application interface.
- Qwen-Max, Qwen-Plus, Qwen-Turbo, Qwen-Long
- Qwen3-Coder-Plus
- Qwen3 open-source models, Qwen2.5 open-source models, Qwen2 open-source models
- Qwen-QwQ, Qwen-QwQ-Preview
- DeepSeek
- Qwen-VL-Max, Qwen-VL-Plus, Qwen-VL-OCR
Supported file formats
- You can upload up to 10 files per session. Each file must be no larger than 10 MB.
- Uploaded files are valid only in the current session. Refreshing or closing the page will delete them. Complete your tasks promptly.
- Documents:
.doc,.docx,.ppt,.pptx,.xls,.xlsx,.md,.txt,.pdf. - Images:
.png,.jpg,.jpeg,.bmp,.gif. - Videos:
.mp4,.mkv,.avi,.mov,.wmv,.webm,.flv. - Audio:
.aac,.amr,.flac,.m4a,.mp3,.mpeg,.ogg,.opus,.wav,.wma.
How to use
Full-text citation
Steps
- Select a model in the agent application.
- In the File Processing module, select Full-text Reference.
- In the debugging window on the right, click the upload icon next to the input box to upload a local file. Then ask questions about its content.
Parameter settings
Click the configuration icon to open the configuration page:
- Maximum Parse Length per File (tokens): Limits how many tokens the system extracts from a single file. Content beyond this limit is truncated from the end of the file.
- Maximum Assembly Length: Limits the total number of tokens across all files. Content beyond this limit is truncated from the end of the last assembled file.
When enabled, Full-text citation delivers parsed file content directly to the agent and automatically truncates oversized content. To avoid losing information, set Maximum Parse Length per File (tokens) carefully—or use Chunk Retrieval for long files.
Example
Upload Alibaba Cloud Model Studio Mobile Product Introduction.docx. Ask: “Summarize the content of this file.”
The AI assistant returns a file summary: the document introduces six smartphone models under the Alibaba Cloud Model Studio (Bailian), Tongyi, and Xingchen brands, with a product overview table listing each model's name, key features, screen, and storage/RAM information.
Segment Retrieval
Parameter settings
Click the configuration icon to open the configuration page:
- Number of Recalled Chunks: Maximum number of text fragments the model references when answering. Valid range: 1–20.
- Maximum Assembly Length: Limits the total token count of all recalled fragments. Valid range: 1–98304. If exceeded, the system discards the lowest-scoring fragments until the limit is met.
When Chunk Retrieval is enabled, the system performs complex, intent-aware planning and retrieval using both the query and the knowledge base. Alternatively, you can select Custom Processing mode, in which the agent autonomously plans and invokes tools.
Search only the uploaded file
Steps
- Select a model in the agent application.
- In the File Processing module, select Chunk Retrieval.
- In the debugging window on the right, click the upload icon to upload a local file. Then ask questions about its content.
Example
Upload Alibaba Cloud Model Studio Mobile Product Introduction.docx. Ask: “Recommend a smartphone around CNY 5,000.” The system performs knowledge retrieval on the uploaded file and returns 4 results (scores 0.99, 0.47, 0.46, 0.44). Based on the retrieved content, the AI generates a smartphone recommendation—for example, “Alibaba Cloud Model Studio X1”, priced at CNY 4,599–4,999, highlighting its screen, performance, battery life, and imaging.Hybrid retrieval: file + knowledge base
Steps
- Select a model in the agent application.
- In the File Processing module, select Chunk Retrieval.
- In the Knowledge module, click the + button to select and add an existing knowledge base. If none exists, create one first on the knowledge base page.
- In the debugging window on the right, click the upload icon to upload a local file. You can now ask questions using both the uploaded file and the linked knowledge base.
Example
Add a video file to your knowledge base first. Then click the upload icon in the input box to upload test.mp4. Ask: “Does any person in this video appear in the knowledge base?” The system performs knowledge retrieval and returns two results. After comparing them, the AI assistant determines that the real person in the video does not match the anime-style illustrations in the knowledge base and replies that the person in the video does not appear in the knowledge base.Custom processing
Steps
- Select a model in the agent application.
- In the File Processing module, select Custom Processing.
- Under Skills, add the required tools—such as the MCP Server or plugins.
- In the debugging window on the right, click the upload icon to upload a file. Then provide instructions in chat to let the model call the configured tools to process it.
Image processing settings for specific models
After you select a Qwen-VL series model and upload a file, click the configuration icon to configure processing options.
In custom processing mode, file handling logic varies by type:
-
Image files: Choose one of the following options:
- Model-only processing: The model uses its built-in visual capabilities to analyze the image and answer directly—without calling external tools. This option is best for visual Q&A.
- Model processing + planning: After analyzing the image, the model decides whether to call your configured external tools—such as plugins—for more complex tasks. This option is best for editing, transforming, or analyzing images with tools.
- Other files (documents, audio, video): The model autonomously decides whether to call tools.
Example
Agent configuration:
- Select a Qwen-VL series model. Click the configuration icon next to Custom processing and set image processing to Model processing + planning.
- Under MCPS, add the Character style re-rendering tool.
MCP: bailian_image_style_repaint tool and successfully transforms the uploaded portrait into a vibrant cartoon-style image.
API reference
Prerequisites
- Application publishing: You must publish your application in the console before you can call the API.
- Processing mode: Files are processed using the mode that is saved in your agent application—such as full-text citation or chunked retrieval. You cannot change the mode dynamically during API calls.
Call limits
File Q&A API calls follow the unified rate-limiting policy of the associated agent application.
- Default limit: Up to 100 calls per minute per agent application.
- Shared quota: This limit applies to all API requests to the application—including File Q&A calls and other API requests. For example, if you make 50 File Q&A calls in one minute, only 50 calls remain for other API requests.
File delivery methods and parameters
| File delivery method | API parameter | Main use case / key traits |
|---|---|---|
Pass image URLs via the image_list parameter | image_list | For image retrieval and visual understanding. Max file size: 10 MB. |
Pass generic file URLs via the file_list parameter | file_list | Passes generic file URLs. In full-text citation/chunked retrieval mode, the system extracts and uses the file's text. In custom processing mode, the model receives the raw file URL to call tools. Max file size: 10 MB. |
| Use the file upload API | session_file_id | Recommended for production environments. Workflow: 1. Call the file upload API to upload the file and get a session_file_id. 2. Pass this ID in your chat API request. Benefits: Supports larger files and offers more stable transfers. |
Billing
- File upload: Uploading files is free of charge.
- Model calls: Q&A based on file content consumes input and output tokens. You are charged at the standard rate for your selected model. For more information, see the Model List. Token usage varies by mode:
- Full-text citation: The entire file—or the truncated version—is passed as input. Input token usage is high.
- Chunked retrieval: Only your question and the most relevant retrieved fragments are passed as input. Input token usage is typically much lower—ideal for long documents.
- Custom processing: Token usage depends on interaction complexity—such as interpreting your instruction, calling tools, and summarizing tool results.
- Tool calls: Some tools incur fees. Pricing is available on the tool's details page.
FAQ
- How do I provide a publicly accessible file URL for the API? We recommend Object Storage Service (OSS). It provides highly available, reliable storage and enables you to easily generate public URLs. Ensure your URL is accessible to Alibaba Cloud Model Studio services. Test it in a browser or with curl to confirm the file downloads successfully.
-
How long is a file valid?
- Uploaded via chat window: Valid only in the current session. Files expire if you close or refresh the page—or if the session times out.
- Uploaded via file upload API (
session_file_id): Typically valid for 24 hours. - Provided via URL (
image_list,file_list): Validity depends entirely on your URL.
-
Why did my file upload fail?
Upload failures may result from several causes:
- File issues: Check file size and format against the supported file formats.
- Network issues: Check your network connection and connectivity to the service endpoint.
- URL issues: Confirm the URL is publicly accessible and not a temporary signed URL.
- API issues: Verify your authentication credentials and parameter formatting.
- Error messages: Read the API response body. It usually identifies the exact issue.
-
Why is the model's answer incomplete or inaccurate?
Possible reasons:
- Content truncation: File content was cut off due to token limits. In full-text citation mode, increase “Max tokens per file” and “Max assembled tokens”. For very long files, switch to chunked retrieval.
- Vague questions: Be more specific. Clearly state what information you need so that the model better understands your intent.
- Poor retrieval (chunked retrieval mode): Inaccurate answers may stem from low-quality retrieved fragments or suboptimal chunking. Refine your question for better targeting. Adjust the chunk size in your app settings to improve retrieval coverage.
- Poor file quality: Parsers struggle with low-definition scans, documents with complex tables or formulas, or poorly encoded text files. Provide clear, simple source files whenever possible.
- 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.