美洽知识库导入格式要求

美洽知识库批量导入支持CSV与JSON两种格式，通常要求UTF-8编码，关键字段包括标题、问题、回答、分类、标签、语言、状态和ID；内容允许一定HTML，但换行与逗号需正确转义或用引号包裹，附件以可访问URL形式提供，单条大小建议不超64KB，字段名需精确匹配且建议先在测试环境小批量验证以免映射或编码问题导致导入失败。

先说结论（简要）：哪些是必须的、哪些是可选的

直截了当地说，导入前最重要的是三个点：编码、字段映射与内容格式。UTF-8编码、精准的字段名（标题、问题、回答、分类等）、以及正确处理换行和逗号，几乎能解决大部分导入失败的问题。其他像附件、标签、语言这些属于可选或增强字段，但也有明确的格式要求。

为什么这些规则存在（用费曼方式解释）

想象一下你把一箱纸条交给一个不认识你写法的朋友：如果不说明每张纸条代表“问题”还是“回答”，朋友就无法把它们放到正确的文件夹里。格式就是说明书；编码是字的“语言”，字段名则是“标签”，转义则是告诉系统：“这不是分隔符，只是内容的一部分”。

三个核心概念（再简单解释）

• 编码（Encoding）：用UTF-8可以避免中文乱码。
• 字段名（Headers）：和系统约定好的字段名需要一一对应，大小写敏感或平台敏感需核对。
• 数据清洗（Sanitization）：处理换行、逗号、引号、HTML标签和URL等，防止解析错误。

支持的格式与上传方式

美洽通常支持两种主要方式：通过后台界面上传CSV文件，或通过API提交JSON。选择哪种方式取决于你的数据来源与自动化需求。手动导入用CSV最方便，自动化或程序化导入建议用JSON并结合API做幂等操作。

CSV要点

• 必须使用UTF-8编码；不要用带BOM的UTF-8（部分系统解析会出问题）。
• 默认分隔符为逗号（,），若内容中含逗号，请用双引号包裹该字段。
• 如果字段内含双引号，需用双双引号转义（例如：He said “”hello””）。
• 换行符建议在CSV中以\n表示，但要整条内容被引号包裹。
• 首行为表头，字段名请严格按平台要求命名（参见下表）。

JSON要点

• 总体为UTF-8文本；确保字符串中的特殊字符（如控制字符）正确转义。
• 建议使用数组结构，每个对象代表一条知识（question-answer对）。
• 如果通过API上传，注意接口的认证、批量大小与重试策略。

常见字段说明（表格）

内容与HTML：允许与限制

美洽允许在回答内容中使用有限的HTML标签以便排版，但通常只允许基本结构标签，例如 <p>、<br>、<ul>、<ol>、<li>、<strong>、<em>、<a href>（需有http/https）与<img src>（画像建议通过attachments）。复杂脚本、内嵌样式或iframe通常会被清理或拒绝。

为什么要限制HTML？

主要出于安全和展示稳定性考虑。用户界面需要保证知识库内容在各端（Web、Mobile、第三方客服）都能正常渲染，因此会过滤掉可能破坏布局或带来安全隐患的标签。

字符长度与大小限制

• 标题：建议≤200字符，系统上限可能在500字符左右（以后台提示为准）。
• 回答内容：建议≤64KB（约65,536字节），超长内容请拆分为多个条目或使用附件/链接。
• CSV单文件大小：通常限制在几十MB到上百MB不等，若有大量数据建议分批上传。

附件与图片处理

附件字段接受可公开访问的URL。上传流程通常有两种策略：一是平台抓取并保存资源，二是仅保存外链。建议事先将图片或文件上传到稳定的CDN或对象存储，确保URL在导入时可访问且无防盗链限制。

分批导入与性能注意点

• 不要一次提交巨量数据。建议每批1000条以下（视平台和网络情况而定），先小批量测试。
• 通过API导入时注意接口的速率限制（Rate Limit），并实现指数退避重试策略。
• 记录每次导入的返回结果与错误日志，便于回溯与补救。

字段映射与本地化（国际化）

如果你有多语言内容，建议在同一条记录中使用language字段区分，或为每种语言创建独立条目并使用相同的id加上语言后缀（例如id_zh、id_en）。分类与标签也应同步本地化，避免出现跨语种混乱的检索结果。

导入前的数据清理清单（Checklist）

• 确认CSV/JSON为UTF-8编码；去掉BOM。
• 字段名与示例模板完全一致（大小写与下划线注意）。
• 所有URL可访问且使用https优先。
• CSV中的特殊字符（逗号、换行、双引号）已正确转义或用引号包围。
• 没有空的必填字段；状态字段值合法（draft/published）。
• 为更新操作提供唯一ID以实现幂等性。

常见错误与排查办法

• 中文乱码：多半是编码问题——确保UTF-8并且客户端保存时未转为ANSI/GBK。
• CSV解析失败：检查首行表头是否缺失或字段名拼写错误，确认分隔符是逗号而不是分号。
• 导入后内容被截断或报错：检查字段长度限制与特殊字符；若含HTML，确认是否用允许的标签。
• 图片无法加载：确认图片URL公开可访问并支持https；若有防盗链或临时签名URL，考虑替换或提前抓取。
• 重复条目：使用id字段或明确的去重规则来避免重复插入。

示例：CSV头部与一条示例记录

下面这个表格展示一个简化的CSV头部及一条记录示例，方便你在Excel或脚本中构造。

通过API导入的实务建议

• 使用幂等键（如外部id）避免重复写入。
• 分批（batch）提交并记录每批的回执（比如导入成功数、失败详情）。
• 实现重试逻辑并记录错误信息，以便人工介入修正数据后重试。
• 对比上传前后的记录数与示例条目，确认导入结果一致。

版本与回滚策略

不是所有平台都会保存每次导入的历史版本，所以建议在进行大规模更新前备份现有知识库（导出当前数据）。若平台支持版本控制或草稿-发布流程，先在测试环境或草稿状态验证通过再发布。

自动化同步与去重策略

如果你有外部CMS或产品系统，需要定期同步知识库，可以：

• 用唯一id做主键，比对更新时间字段（updated_at）决定是否更新。
• 使用哈希（如对title+answer做MD5）判断内容是否变化，减少无效写入。
• 对于同义问题，维护一套“query set”字段，方便搜索匹配而不是创建多条重复记录。

常用术语解释（小词典）

• 转义（Escaping）：用于告诉解析器“这是原始内容，不是分隔符”。
• 幂等（Idempotent）：相同请求多次执行，结果不变，便于重试。
• 去重（Deduplication）：防止重复条目造成检索混乱。

实操小贴士（经验之谈）

• 先做一份小批量（10-50条）测试，确认字段映射无误再放大。
• 用脚本生成CSV时，尽量用成熟库（如Python的csv模块）避免手写拼接导致的转义错误。
• 把复杂多媒体或非常长的流程型回答拆分成多条关联条目，便于检索。
• 保持标签和分类的粒度一致，不要过度细分以免混淆检索。

如果遇到无法解决的问题，先这样记录信息

• 上传文件样本（包含问题条目但不含敏感信息）
• 报错信息的完整返回（HTTP状态码与错误体）
• 导入前后的示例ID、时间戳与环境（测试/生产）

好了，以上就是把美洽知识库导入环节拆解后的要点与实操建议。我自己在做导入时也常犯一些小错，比如忘记去掉BOM或把中文Excel另存为ANSI，导致一开始总出错——现在养成先做小批验证的习惯后，问题少多了。如果你想，我可以帮你把现有的CSV/JSON头部检查一遍，或者给你一个可直接用的CSV模板，不过那我们得先看一下你当前的数据样式，然后一步步改好再导入。