第 10 章　接入外部 API

本章的外部API，主要指为WorkBuddy配置自己的模型服务。它与第7章的法律数据库连接器不同：模型API提供理解与生成能力，数据库接口提供专业资料，不能因为接入了新模型就推定有法规或企业信息查询权限。

API可以理解为软件间通信的入口。配置通常需要服务地址、模型名称和API Key，套餐还可能有使用范围、调用频率和费用限制。先确认服务是否允许你的使用方式，再填入WorkBuddy。

准备准确的配置资料

从模型服务提供方的账户控制台取得配置，不从群聊截图照抄别人地址。核对服务域名、账号、模型标识、额度和兼容接口要求。网页会员、Coding Plan、Token Plan与API额度可能是不同产品，不能把网页登录密码当作API Key，也不能把一个套餐的余额理解为另一个接口可用。

为本次配置准备一个可撤销的Key，保存在当前客户端要求的配置位置。不写进普通任务说明、共享文档或公开仓库。需要向他人反馈问题时，提供错误类型、模型名称、时间和脱敏配置，隐藏完整Key与不必要的请求内容。

在模型设置中添加

路径是设置、模型、添加模型，再选择预设服务或自定义API。当前版本若在输入框模型选择器中提供配置入口，也可由该入口进入。以客户端实际字段为准，不必直接编辑配置文件。

图10-1 模型配置画面，定位设置、模型与添加入口；界面字段以当前版本为准。

选择预设提供方后，按页面填Key和必要字段；选择自定义时，按提供方文档填写接口地址和模型标识。接口根地址与完整请求地址可能不同，应使用当前配置说明要求的格式，避免重复拼接路径。保存后，在任务的模型列表中选择刚添加的模型，再开始测试。

官方模型配置说明可用于核对当前入口与第三方服务说明。Key保存在本地配置，并不意味着发送给模型的任务内容也留在本地；实际输入将交给所选服务处理，应同时核对服务的数据规则。

分三步测试

第一步只做简单文本问答，确认认证与模型名称有效。第二步用一份模拟合同段落做信息提取，检查中文、表格和长句处理。第三步才验证任务真正依赖的能力，例如图片读取、工具调用和长资料处理。能回答一句话，不代表能完整运行含工具的法律工作流。

请使用我当前选择的自定义模型完成能力测试。
材料是教学模拟：甲方收到货物并完成验收后30日内支付合同总价10万元。
只从这句话提取：付款主体、付款金额、起算条件、期限及尚未提供的信息。
不得补充签署日期、银行账户或违约责任。
先在对话中给表格，不读本地文件、不联网、不调用外部数据库。
不能确认的内容写“材料未提供”，并说明原文依据。

文本测试通过后，可以复用第4章的小规模合同练习，比较同一材料、同一要求下的结果。记下模型、时间、成本和错误，而不是凭表达流畅度判断质量。视觉不支持时，换用合适模型或独立OCR流程，不能让文字模型推测截图内容。

本地模型的特殊检查

也可以配置本地 Ollama 模型。这里需要先有可用的本地模型服务，再按实际接口、地址和模型名称配置。运行端口与接口路径以服务设置为准，不把某个默认值当成所有电脑都相同。

本地推理可能减少对远程模型的依赖，但仍会占用硬件、内存、电力和维护时间。WorkBuddy任务还可能调用联网检索、远端连接器或云端推送，因此不能笼统宣称整项任务离线、数据绝不出机或使用零成本。希望限定本地处理时，要检查任务的整条链路。

失败与更换服务

认证失败先检查Key是否完整、有效、属于当前服务；模型不存在先核对标识与账号可用列表；超额或限流先查看额度及频率；网络错误先确认地址、代理与服务状态。不要在不知道原因时反复重试大文件任务，以免消耗额度。

怀疑Key泄露时，在服务方控制台撤销并重新生成，再更新客户端配置。更换模型后，用同一练习重新核对，尤其是工具调用、图片处理和结构化输出。生产任务的最终文件仍需人工复核，新接口配置成功不会改变法律交付责任。