文心一言本身并不直接在前端界面提供通用的文档上传入口，文档解析能力通常通过百度智能云千帆大模型平台开放。要把文件交给该平台处理，可以走控制台手动上传、HTTP API 直传或通过后端 SDK 调用三条路径。不同路径对文件格式、大小限制和获取结果的方式都有差异，下面分别说明。
一、在控制台直接上传文件
如果只是想快速验证文心一言对某个 PDF 或 Word 文档的解析效果，最省事的方式是登录百度智能云控制台，进入千帆大模型平台。没有开通服务的话，先按页面提示开通相关功能。文档解析入口一般位于数据处理或知识库菜单下，不同版本界面可能略有差异，但核心流程都是新建数据集或语料库，然后点击上传文档。
控制台中可以选择本地文件，常见支持格式包括 PDF、DOC、DOCX、TXT、XLSX 等。上传时要注意单个文件的大小限制，通常在 15MB 以内，部分场景支持到 50MB；页数方面也会有限制，比如不超过 100 页或 200 页。文件上传后系统会自动进入解析流程，状态列会显示排队中、解析中、成功或失败。控制台上传适合少量文件的人工验证，不适合需要在业务系统中频繁自动调用的场景。
二、通过 HTTP API 上传本地文件
如果要在自己的后端服务中自动上传文档，需要使用 HTTP API。调用前必须获取 access_token，这个令牌由百度智能云的应用 API Key 和 Secret Key 换取。access_token 默认有效期一般为 30 天，过期后需要重新获取。拿到令牌后，再把文件通过 multipart/form-data 形式发送到文档上传接口，响应中会返回文件 ID 或任务 ID，后续解析时需要用到。
获取 access_token 的 Python 示例代码如下：
import requests
API_KEY = "your_api_key"
SECRET_KEY = "your_secret_key"
url = "https://aip.baidubce.com/oauth/2.0/token"
params = {
"grant_type": "client_credentials",
"client_id": API_KEY,
"client_secret": SECRET_KEY
}
resp = requests.post(url, params=params)
print(resp.json().get("access_token"))
拿到 access_token 后，可以继续上传文件。下面这段代码演示了如何上传一个本地 PDF 文件，并附带文件名和格式参数。实际接口地址和参数名可能随平台版本调整，建议以官方 API 文档为准，但整体思路是一样的。
import requests
access_token = "从上一步获取的access_token"
upload_url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/document/upload"
headers = {
"Content-Type": "application/json"
}
params = {
"access_token": access_token,
"file_name": "report.pdf",
"file_format": "pdf"
}
files = {
"file": open("report.pdf", "rb")
}
resp = requests.post(upload_url, params=params, files=files, headers=headers)
print(resp.json())
上传成功后的响应里通常包含一个 file_id 或 task_id，这个标识要保存下来，后续查询解析状态和获取解析结果都会用到。需要注意的是，不要把 API Key 和 Secret Key 硬编码在源代码里，更不要提交到公开仓库。生产环境建议通过环境变量或配置中心读取。
三、前端页面先选文件再交给后端代理
前端页面承担的是文件选择和上传交互。虽然理论上浏览器也能直接调用百度接口，但这会暴露 API Key 和 Secret Key，并且可能遇到跨域限制。更安全的做法是前端把文件传到自己的后端服务，由后端统一携带密钥调用百度文档解析接口，这样密钥不会出现在浏览器端。
下面的前端代码实现了一个简单的上传表单。页面需要一个 <input type="file"> 元素来读取本地文件，监听表单提交事件，用 FormData 包装文件后发送给后端地址 /api/upload-document。
<form id="uploadForm">
<input type="file" id="fileInput" accept=".pdf,.doc,.docx,.txt" />
<button type="submit">上传</button>
</form>
<script>
document.getElementById("uploadForm").addEventListener("submit", async function (e) {
e.preventDefault();
const file = document.getElementById("fileInput").files[0];
if (!file) return alert("请选择文件");
const formData = new FormData();
formData.append("file", file);
formData.append("file_name", file.name);
const response = await fetch("/api/upload-document", {
method: "POST",
body: formData
});
const result = await response.json();
console.log(result);
});
</script>
后端收到文件后，可以先做一次基础校验，比如检查扩展名是否在允许列表中、文件大小是否超过限制。校验通过后再调用上一小节介绍的 HTTP API，把文件转发到百度侧。这样做还能统一记录日志、控制调用频率，避免前端直接上传带来的安全风险。
四、解析结果获取与常见问题
文件上传完成并不代表解析已经结束。大文件解析通常需要几秒到几十秒，服务端会异步处理。因此调用上传接口拿到 task_id 后，还需要轮询查询解析状态。轮询间隔建议设置为 3 到 5 秒，同时设置一个最大超时时间，比如 120 秒，避免任务一直挂起。
下面是一个简化版的轮询示例，用于查询任务是否解析完成。实际返回状态可能包括排队中、处理中、成功和失败，可以根据状态决定继续等待还是返回错误信息。
import time
import requests
def wait_for_parse(access_token, task_id, timeout=120):
url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/document/query"
params = {"access_token": access_token, "task_id": task_id}
while timeout > 0:
resp = requests.post(url, params=params).json()
if resp.get("status") in ("success", "failed"):
return resp
time.sleep(3)
timeout -= 3
return {"status": "timeout"}
在上传和解析过程中，有几个高频问题需要留意。第一是格式不支持，虽然接口宣称支持多种文件，但加密 PDF、扫描件或旧版 DOC 可能无法解析，扫描版 PDF 需要额外开启 OCR 能力。第二是页数超限，长篇文档建议先拆分再上传。第三是鉴权失败，检查 access_token 是否过期，以及请求参数中是否正确携带了令牌。第四是文件大小超限，压缩普通图片没有意义，因为 PDF 本身已经是压缩格式，应优先减少页数或拆分文件。
如果平台支持公网 URL 上传，也可以先把文件放到对象存储中，再把可公开访问的 URL 传给解析接口。这种方式适合文件已经存储在云端的场景，但要注意 URL 不能带访问控制签名，否则百度侧无法下载文件。无论走哪种上传路径，最终目标都是让文档尽快进入解析队列，并用稳定的轮询机制拿到结构化结果。