下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/user_af179082--ima-file-upload.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_af179082/ima-file-upload。- 把本地文件(PDF/Word/PPT/图片等)批量上传到腾讯 IMA 知识库。当用户说"
- 传到IMA"
- "
- 放进IMA知识库"
- "
- 导入ima"
- …(完整说明见下方「阅读全文」)
阅读全文 (展开查看完整说明)
概述
IMA 知识库文件上传
前置检查
ima-mcp连接器必须为 connected,否则工具不可用,需让用户在连接器管理页手动连接。- IMA MCP 没有
create_knowledge_base工具 —— 无法新建知识库,只能往已有的写。
用 get_addable_knowledge_base_list(分页,limit 50)列出可写入的库。
- 用户口中的「XX知识库」很可能是某个知识库下的文件夹。若
search_knowledge_base查不到同名库,
务必用 get_knowledge_list 查根目录,看是否存在同名文件夹(media_type: 99)。
三步上传流程
1. create_media —— 申请 COS 临时凭证
mcp__ima-mcp__create_media {
knowledge_base_id, file_name, file_ext, file_size, content_type
}file_size必须是精确字节数,服务端据此校验上限,不符会拒绝。content_type必须按扩展名精确填(pdf→application/pdf),禁止用 octet-stream 兜底。- 返回
media_id+cos_credential(token / secret_id / secret_key / bucket_name / region / cos_key),
凭证有效期约 12 小时。
- 每个文件都要单独调一次,凭证不能复用。
2. PUT 上传到 COS
不要等 pip install cos-python-sdk-v5(很慢),直接用 scripts/cos_put.py 里的零依赖实现。
调用方式:先把 create_media 的返回整理成任务清单 JSON,再执行脚本。
python scripts/cos_put.py tasks.jsontasks.json 格式(数组,每个文件一项):
[
{
"path": "C:/abs/path/文件.pdf",
"media_id": "pdf_xxx...",
"cred": {
"token": "...", "secret_id": "...", "secret_key": "...",
"bucket_name": "...", "region": "ap-xxx", "cos_key": "..."
}
}
]cred 直接照抄 create_media 返回的 cos_credential。脚本串行上传并输出 upload_result.json。
⚠️ 用完立即删除
tasks.json—— 里面是明文临时密钥,不要留在工作区或提交到仓库。
核心签名算法(COS Signature v5 / sha1):
KeyTime = "{start};{end}" # unix 秒
SignKey = HMAC-SHA1(secret_key, KeyTime).hex()
HttpString = "putn{uri}nn{urlencoded_sorted_headers}n"
StringToSign = "sha1n{KeyTime}n{SHA1(HttpString).hex()}n"
Signature = HMAC-SHA1(SignKey, StringToSign).hex()请求要点:
- URL =
https://{bucket_name}.cos.{region}.myqcloud.com/{cos_key}
(bucket_name 已含 appid,不要再拼)
- 参与签名的 header 只放
host+content-type,值需 URL 编码(safe='-_.~') - 临时密钥的
x-cos-security-token作为 header 传,不参与签名 q-url-param-list留空
3. add_knowledge —— 入库
mcp__ima-mcp__add_knowledge {
knowledge_base_id, media_id,
folder_id?, # 直接指定可一步到位
duplicate_name_strategy: "DUPLICATE_NAME_STRATEGY_SAVE"
}最佳实践:第一次调用就带上 folder_id,省掉后面的移动步骤。
归置到文件夹(重要技巧)
IMA MCP 没有 move / delete 工具。若文件已入根目录想挪进文件夹:
再次调用
add_knowledge,传同一个media_id+ 目标folder_id,策略用
DUPLICATE_NAME_STRATEGY_REPLACE。这是移动而非复制 —— 已实测验证,根目录副本会消失。
(knowledge_total_size 短时间内可能虚高,是最终一致性延迟,以文件夹内 total_size 为准。)
文件体积
知识库对单文件有大小上限。扫描版 PDF(整页图片)很容易过百 MB,建议先压到 30MB 以内:用 Pillow 把每页缩放到 1240px 宽 + JPEG q72,体积约降到 1/5,文字仍清晰可检索。
验证
get_knowledge_list 带 folder_id 查看:
media_state: 1=解析中, 2=解析成功parse_progress: 0~100- 解析完成后
introduction会自动填充首页正文摘要,可据此确认内容正确