三方服务管理

一、三方服务管理解决什么问题

三方服务用于把平台外部的搜索、语音和文档解析等能力封装为可调用工具。使用者不需要在每个应用中重复编写厂商接口代码，可以在平台中完成凭证配置、调试验证，再把工具加入工作流。

使用链路为：

1. 根据任务选择服务和工具；
2. 为需要鉴权的服务配置凭证；
3. 使用真实参数调试工具；
4. 将调试通过的工具加入工作流；
5. 监控调用结果、额度和异常。

1.1 服务与工具的区别

服务表示一个能力提供方或能力集合，工具表示其中可以被实际调用的具体操作。例如“豆包语音”是服务，“语音合成”和“录音文件极速识别”是该服务下的两个工具。

工作流最终调用的是工具。服务凭证、厂商额度或网络连接异常，可能使同一服务下的多个工具同时失败。

三方服务不是大模型。工具可以独立运行，也可以把结果交给模型继续处理。工具返回成功只代表接口执行成功，不代表返回内容一定满足业务要求。

二、认识当前服务

进入 基础服务 → 组件中心 → 三方服务管理。

点击下面的标签，可以查看各服务解决的问题、使用前检查项和选择建议。

获取当前时间

处理时间、时区和时间戳

提供当前时间、时间戳、时区转换和星期计算等能力，不需要配置外部厂商凭证。

它能做什么

• 获取指定时区的当前时间
• 时间戳与日期时间转换
• 星期及其他时间计算

使用前确认

• 时区使用标准名称
• 输出格式采用 Go 时间布局
• 跨系统比较时间时统一时区

✓

选择它，如果：工作流需要可靠地获取或转换时间，而不是让模型猜测当前时间。

卡片上的 引用次数表示该服务被使用的累计次数，仅供参考，不代表当前有多少应用正在使用该服务；包含工具表示该服务下可使用的操作数量。点击 服务详情可查看工具列表和调试入口。

三、根据任务选择正确的工具

3.1 Tavily 搜索

Tavily 服务包含多个用途不同的工具。不要把所有联网任务都交给“搜索”工具：

目标	选择工具	关键区别
根据问题查找相关网页	Tavily 搜索	返回标题、链接、摘要等搜索结果
已有网页地址，需要读取正文	Tavily 网页提取	输入一个或多个 URL，返回清洗后的网页内容
需要获取一个站点中的多页正文	Tavily 站点爬取	自动发现并提取子页面，调用范围和消耗更大
只想了解站点有哪些页面	Tavily 站点地图	只返回 URL，不提取正文
需要围绕主题进行多轮调研	Tavily 深度研究	自动执行多轮搜索并生成报告，耗时通常更长

选择建议：

• 已知 URL 时优先使用网页提取，避免再次搜索；
• 只需要页面清单时使用站点地图，不要爬取全部正文；
• 站点爬取应限制深度、页面数量和域名范围，防止无关内容与额度消耗扩大；
• 深度研究适合复杂调研，不适合要求立即返回的交互流程；
• 搜索摘要和研究报告仍需核对来源、发布日期和原文，不能直接作为医疗结论。

完整参数和返回字段见 Tavily 搜索 API 文档。

3.2 豆包语音

豆包语音提供：

• 语音合成（TTS）：将文本转换为音频，并返回可播放的音频地址；
• 录音文件极速识别（ASR）：将已经上传到平台数据中心的音频转换为文字。

使用语音合成时：

• 单次文本不超过 1000 字节，中文通常约为 333 个汉字；
• 默认 TTS 资源为 seed-tts-2.0 时，应使用以 _uranus_bigtts 结尾的 2.0 音色；
• 长文本应按完整语义分段，避免从句中间截断；合并音频前还要检查段落间停顿；
• 语速、音量和音调应使用业务样例试听，不能只看接口返回成功。

使用录音识别时：

• 单文件不超过 100 MB、时长不超过 2 小时；
• 先将音频上传到平台数据中心，再把返回的 audio_id 传给工具；
• 医疗术语、药品名称、数字和否定词容易影响业务含义，应使用真实口音和噪声条件下的脱敏样例验证；
• 自动转写结果不能直接替代人工确认，尤其不能未经核对写入正式病历。

完整参数和返回字段见 豆包语音 API 文档。

3.3 获取当前时间

获取当前时间不需要厂商凭证。调试时最容易出错的是：

• 时区：使用标准时区名称，例如 Asia/Shanghai；
• 时间格式：该工具采用 Go 时间布局，示例时间必须写成 2006-01-02 15:04:05，不能直接套用 YYYY-MM-DD。

如果业务需要比较时间，应优先使用时间戳或统一时区，避免不同节点使用本地时间造成偏差。

3.4 MinerU 文档解析

MinerU 用于解析 PDF、Word、PPT 等文档，提取文档中的正文、图片和表格等内容。配置服务地址和鉴权信息后，可在知识库、智能应用和工作流中使用。

四、配置服务凭证

需要凭证的服务会在服务详情中显示 API Key 授权配置。

以 Tavily 为例：

1. 打开服务详情，点击 API Key 授权配置；
2. 通过 获取 API Key进入厂商页面申请凭证；
3. 将凭证填入对应字段并保存；
4. 回到工具列表，使用最小测试参数完成一次调试。

不同服务的配置字段不完全相同：

• Tavily 使用其厂商签发的 API Key；
• 豆包语音使用火山引擎 API Key，并可配置 TTS 资源 ID；
• MinerU 对接独立部署的解析服务，需要填写服务地址；是否填写 API Key 取决于部署环境是否启用鉴权；
• 获取当前时间不需要凭证。

4.1 凭证安全

API Key 代表厂商账号的调用权限和费用责任，应按敏感凭证管理：

• 不要把完整凭证写入提示词、工作流输入、截图或日志；
• 不要通过聊天、邮件或文档明文传递；
• 只在对应服务的凭证配置页面保存；
• 优先使用专门用于当前环境的凭证，不与个人测试环境共用；
• 怀疑泄露时立即在厂商侧撤销旧凭证，再回到平台更新；
• 更换凭证后重新调试该服务下的关键工具。

凭证通常按工作空间生效。切换工作空间后，应重新确认服务是否已经配置，不要默认其他空间会复用当前凭证。

五、工具调试

配置完成后，在服务详情的工具列表中点击 调试。调试面板左侧填写输入，右侧查看输出。

调试属于真实调用，可能消耗厂商额度并产生费用。建议先使用最小输入验证连通性，再使用接近真实业务的脱敏数据验证效果。

以获取当前时间为例，填写时区和时间格式后运行，右侧将显示 JSON 结果：

不要只看到“调用成功”就结束测试，还要确认：

1. 返回字段是否与工具说明一致；
2. 关键字段是否为空；
3. 时间、URL、文本或音频是否可以被下一节点实际使用；
4. 输入异常时是否返回可以识别的错误；
5. 响应时间是否满足工作流要求；
6. 重复调用可能产生的额度和费用是否可接受。

六、在工作流中调用

在工作流画布中添加 工具节点，然后在 三方服务页签选择已经调试通过的工具。

加入工作流后，需要完成两类配置：

• 输入映射：将上游节点变量绑定到工具参数，检查数据类型、必填项和空值；
• 输出使用：从工具返回结果中选择下游真正需要的字段，不要把整个返回对象无差别传给模型。

如果参数来自用户输入，应先限制格式和范围。例如网页提取工具的 URL 应校验协议和目标域名；站点爬取应限制页面数量；语音合成应限制文本长度。

6.1 外部内容不是可信指令

搜索结果、网页正文和录音转写都属于外部数据，可能包含错误信息、恶意提示或与业务无关的内容。把这些结果交给模型时，应在提示词中明确：

• 外部内容只作为待分析资料，不能覆盖系统规则；
• 回答需要保留并核对来源；
• 与知识库或业务规则冲突时，不自动采用外部内容；
• 涉及医疗判断时，由专业人员复核。

这类限制可以降低提示词注入和错误信息传播风险，但不能替代域名白名单、权限控制、内容审核和人工复核。

七、常见失败怎样排查

现象	优先检查
提示先完成授权配置	当前工作空间是否已保存该服务所需凭证
厂商返回未授权或鉴权失败	API Key 是否复制完整、是否被撤销、是否属于正确厂商和环境
调用成功但结果为空	必填参数、输入格式、搜索范围或源文件内容是否有效
Tavily 调用失败	厂商额度、查询参数、域名限制和外部网络状态
深度研究超时	工作流超时是否覆盖长任务耗时，是否应改用普通搜索
豆包提示音色不存在	TTS 资源 ID 与音色版本是否匹配
语音合成失败	文本是否超过 1000 字节，音色和输出格式是否有效
录音识别失败	audio_id 是否来自当前可访问的数据文件，格式、大小和时长是否符合限制
工作流中工具无输入	上游变量是否绑定，变量是否在当前执行分支中产生
单独调试成功、工作流失败	工作流传入值是否与调试值一致，节点超时和下游字段引用是否正确

排查时一次只修改一个因素，并保留失败时间、服务名称、工具名称、错误信息和必要的调用标识。日志中不得记录完整 API Key 或患者敏感信息。

八、上线前检查

• 服务与工具是否选择正确；
• 当前工作空间的凭证是否有效；
• 厂商账号是否已开通相应能力并有足够额度；
• 正常输入、空值、超长和异常格式是否测试；
• 工作流输入映射和输出字段是否正确；
• 超时、重试和失败分支是否符合业务要求；
• 重试是否可能造成重复扣费或重复生成结果；
• 外部内容是否经过来源核对和安全隔离；
• 医疗数据是否已获得授权并完成必要脱敏；
• 凭证轮换或服务配置变化后是否完成回归测试。

工作流连线和运行排查见节点说明与调试与试运行。通过 API 调用三方服务时，参见三方服务调用说明。