文件库

文件库是涂鸦开发者平台提供的私有内容管理与检索能力，面向有私有内容资源托管需求的 B 端开发者。

在面向私有内容资源托管的场景中，平台提供统一的文件存储、文件自定义键值对（Key-Value，KV） 标签管理与打标、文件向量检索的能力。开发者可通过调用平台文件库能力，实现文件存储托管、文件检索及获取文件地址等场景应用。

功能特点

• 通用文件存储：支持音频文件上传与管理。文件上传后系统自动提取格式、码率、时长、大小等元数据，无需开发者手动维护。后续还将支持多模态文件类型。

• 支持全球数据区：文件一次上传，全球数据区自动同步。满足不同地区的业务部署需求，支持海外客户场景。

• 灵活的 KV 标签系统：通过开发者自定义键值对标签实现灵活个性化的内容分类管理与应用，适用于更广泛的业务场景，例如音乐播放、专辑维护、资源分类权益等。支持业务域隔离，同一 Key 在不同业务域下可维护独立的 Value 集合。

• 语义向量检索：支持基于 KV 的向量化检索。KV 标签自动向量化，语义级别的模糊检索，用户输入自然语言即可直接匹配对应的文件内容，无需精确关键词。

• 灵活快速集成：平台提供标准化文件库开放 API，开发者可以通过调用 API 自行开发专有服务，将业务逻辑完全掌控在自己手中，实现可插拔扩展。

名词解释

名词	解释
文件库	涂鸦开发者平台提供的私有文件存储空间，支持文件管理和基于 KV 标签的向量检索
KV 标签	键值对形式的文件标签，Key 和 Value 均为开发者自定义字符串，用于文件分类、内容逻辑隔离和向量检索。例如：key:value = 风格:抒情，key:value = 心情:愉快
Key 描述	为 KV 的 Key 字段附加的自然语言描述，帮助 LLM 理解该标签含义，用于在文件检索时，从用户输入中提取对应的 Value 值
业务域	KV 标签的隔离维度，按文件格式预设（目前为系统预设，例如 .mp3/.mp4 识别为音乐业务，.jpg/.png 识别为图片业务）。同一 Key 在不同业务域下维护独立的 Value 集合。目前只支持音乐业务域

场景实践

涂鸦提供了通过涂鸦设备播放私有音乐功能的最佳实践，使 LLM 不再局限于对话工具，而是扩展为可调用私有内容的智能助手。

方案架构

通过 “平台通用存储 + 自定义 MCP Server + 智能体” 的分层架构 ，文件库为 MCP 提供便捷的内容源接入。具体业务逻辑（如音乐播放、内容推荐）由开发者自定义实现，并通过智能体 Tool Calls 实现通过自然语言播放私有内容。

快速接入指南

第一步：进入文件库

前往 涂鸦开发者平台 > 智能体 > 内容管理 > 文件库 页面。

第二步：上传文件并配置 KV 标签

1. 在文件管理页面上传音频文件：支持 MP3/MP4 文件，单文件大小 ≤ 5 MB，码率 ≤ 128 kbps。
2. 上传完成后，为每个文件打标 KV 标签，并为每个 Key 添加描述字段，帮助 LLM 理解标签含义。

第三步：订阅文件库 API 云服务

在 云开发 > 云服务 找到 文件库 API 云服务，订阅 文件库 API 并授权给对应的云项目，获取访问凭证。

第四步：开发自定义 MCP Server

基于文件库 API 开发 MCP Server，封装业务逻辑。

涂鸦已经发布了开源 MCP 播控服务，您可访问 GitHub 获取。

第五步：部署自定义 MCP Server，并注册到平台

您需要部署自己的 MCP Server，然后主动注册到涂鸦开发者平台。

• 如果是 WebSocket 协议，您可以申请 endpoint 接入。
• 如果是 SSE 或 StreamableHTTP 协议，您需要联系涂鸦进行配置。

关于接入自定义 MCP 到涂鸦平台，请参考 自定义 MCP 服务。

第六步：在智能体编排中添加 MCP 工具

选择要添加私有音乐播放功能的智能体，进入智能体编排页面，在 技能 > 工具集 中添加已注册的自定义 MCP 工具。

第七步：将智能体投放到目标产品 ID

将编排好的智能体发布并投放到目标 PID，对应的设备即可具有通过自然语言对话实现播放您私有音频文件的能力。

文件库

上传文件

1. 登录 涂鸦开发者平台 > 智能体 > 内容管理 > 文件库 前往 文件库 页面。初次访问时需要先订阅文件库存储增值服务。目前文件库存储服务免费，详细费用请参考 费用说明 。

   目前文件库 只支持音频文件，以下说明均指音频文件，要求如下：

   规格	要求
   文件格式	MP3、MP4、WAV
   文件大小	≤ 5 MB
   码率	≤ 128 kbps

2. 单击 文件上传 前往文件上传页面。文件库支持单个/批量文件上传。

   

3. 在文件上传页面，单次最多支持上传 50 个文件。上传文件后，可设置单个文件或批量设置多个文件的语种和标签。

   单击 提交文件 保存。如果文件上传发生错误，系统将只保存有效的文件。

   

管理文件

文件上传完成后，默认为启用状态，可手动停用。停用后，在调用文件库进行向量检索时，将不会召回停用状态的文件切片。

文件列表页支持查看文件的元数据详情以及文件预览（音频文件为试听）。您可以在文件列表页对已保存的文件进行批量修改语种、设置标签、启用/停用以及删除等操作。

关于如何设置标签，请参考 KV 标签管理。

KV 标签管理

KV 标签是用以标识文件属性的元数据标识，支持灵活的自定义设置。开发者可以基于文件标签对文件进行个性化的分类和检索。

KV 标签管理是独立的全局服务，支持文件级别打标标签。KV 存储为涂鸦开发者平台账号维度，账号下所有文件共享标签键。

标签规则

规则项	说明
Key 长度限制	String 类型，≤ 128 字符
Value 长度限制	String 类型，≤ 256 字符
单文件标签上限	一个文件最多绑定 50 个 KV 标签
Key Value 键值关系	同一文件下一个 Key 只能对应一个 Value。在涂鸦开发者平台账号维度下，一个 Key 可以对应多个 Value
大小写	Key 和 Value 不区分大小写
多语言	Key 和 Value 不区分多语言

设置标签

平台支持对单个/多个文件设置标签。您可以手动录入每个 KV，也可以通过标准文本格式批量设置多个 KV。

1. 单击文件标签，或 设置标签。

2. 手动逐个添加/删除标签，或切换为 批量添加 并根据输入规范一次性添加多个标签。如同时选择多个要编辑的文件，可以按照同样的步骤逐个手动添加/批量录入标签。设置完成后，单击 保存标签。

   

   

管理标签

在文件列表页，单击 标签管理 进入管理页面。您可以在列表中看到所有已录入的 KV 标签。所有标签按 Key 列出，并展示 Key 对应的 Value 值以及打标的文件数量。

修改标签键的值

平台支持重命名 Key 键值，以及批量修改 Value 键值。

单击列表右上角的 替换标签值，输入需要替换的 Value 后单击 确定。例如，将原 Value 键值 sleep 修改为 morning；提交后，该 Value 值将在全局显示为 morning。

添加 Key 描述

什么是 Key 描述？

Key 描述用于指导 LLM 从用户输入中提取对应的 Value 值，是实现语义召回的关键配置。

描述字段应包含：Key 的明确含义、常见同义表达、Value 的格式说明（例如 “四位数字”、“枚举值” 等）。示例如下：

{
  "key": "artist",
  "tagKeyDesc": "歌曲的演唱者姓名，可以是单个歌手或组合名称。例如：周杰伦、林俊杰、五月天。用户可能说 “演唱者”、“谁唱的”、“歌手是...”。"
}

{
  "key": "release_year",
  "tagKeyDesc": "歌曲发行的年份，是一个四位数字。例如：2020、2022、2023。用户可能说 “发行年份”、“哪一年的歌”、“XX年后的歌”。"
}

编辑 Key 描述

平台支持手动添加每个 Key 的描述，也支持通过 JSON 格式批量维护 Key 描述。

1. 前往 涂鸦开发者平台 > 智能体 > 内容管理 > 文件库 > 标签管理 页面，在标签列表中选择需要修改的 Key，单击列表右上角 批量编辑标签描述。您可选择 手动输入 或者通过 JSON 导入。

   

2. 若选择手动输入，单击 手动输入，并在文本框中按建议的标准格式录入描述。您也可以输入简短的描述语义后，单击 AI 生成描述 让 AI 为您优化成适合的文案。

   

3. 若选择通过 JSON 代码批量导入，单击 JSON 导入。将已编辑好的 JSON 代码粘贴到文本框中，单击 解析JSON 进行批量解析预览，然后单击 确定 进行批量提交。如果您需要通过 AI 生成描述，将简短的语义说明填写到 tagKeyDesc 字段 的 "xxx" 描述内，然后单击 AI 生成描述。

   

4. 单击 JSON 导出，可以导出当前选中的 Key 描述的 JSON 文件来进行线下编辑。编辑完成后通过 JSON 批量导入，或应用在其他业务场景。

KV 标签设计建议

• 使用语义相对明确的键值。例如：Key=artist，Value=Jessie；Key=style，Value = peace；Key=instrument，Value=piano。方便运营人员管理，也便于 LLM 理解和引用。
• Key 描述字段按标准规范设置。Key 描述直接影响 LLM 的召回质量，建议包含：Key 的明确含义、常见同义词表达、Value 的格式说明（例如 “四位数"、"枚举值“ 等）。
• KV 标签键值中禁止存储敏感信息（如密码、身份证号、手机号等个人隐私数据），避免安全合规风险。
• 提前规划目标业务域以及业务标签库，避免后期大量修改和迁移，影响标签维护以及使用效果。
• 平台不内置内容库逻辑隔离，需要在开发自有服务时通过 KV 标签自行实现，建议在设计阶段就明确各业务的内容访问边界。

向量化与文件检索

文件上传并设置标签后，系统将自动对标签进行向量化，用以在集成文件库功能时，对文件进行语义检索。目前平台只支持对文件元数据进行检索，不支持文件本身内容检索。

文件语义检索的功能只支持通过 OpenAPI 的方式进行集成调用，不支持在涂鸦开发者平台的前台页面行使用。详情请查看下文 文件库 API 集成。

文件库 API 集成

文件库 API 是涂鸦开发者平台提供的开放云服务。通过订阅云服务，您自己开发的服务即可通过 OpenAPI 调用文件库能力，进行基于 KV 标签的语义检索，并获取文件地址。

关于文件库 API 接口文档，请前往 文件库 API。

费用说明

涂鸦文件托管服务为付费服务，文件上传成功后，将消耗相应的存储额度。目前平台提供 1 GB 额度的免费版本，全球数据区可访问。您可订阅 AI 内容存储 增值服务后使用。

超出容量后，无法继续上传新文件。已上传文件可正常使用。如果需要扩容，请联系人工客服。