API 接入：把服务接进工作流程 ​

基础功能 · 模型配置 · 外部业务接口 · 小样验证

API 可以理解为软件之间约定的办事窗口。管理者需要说清楚“向哪个系统、查询什么、拿回来做什么”，并看懂结果是否可信。具体代码可以交给 AI 或技术同事，但服务地址、账号范围和业务口径必须清楚。

本节交付

一张模型配置核对表、一份业务接口任务单，以及一次模拟请求的验收记录。已有测试服务的学员再完成真实连通验证；没有账号与密钥的学员照样可以完成文档分析和模拟响应练习。

先分清两种 API ​

你要解决的问题对应接入在哪里起作用地产业务例子
让 WorkBuddy 使用企业已采购的大模型模型 API设置里的模型配置，改变本次任务调用的模型服务使用企业允许的模型分析项目材料
让 AI 读取系统数据或调用外部工具业务 API／连接器连接器、MCP 或按服务文档编写的脚本查询项目月度指标、读取合同台账、查询会议资料

模型 API Key 只能访问相应模型服务；它不会自动开通明源、财务系统或 ima 的业务权限。业务系统提供一个 HTTP API，也需要适配为 WorkBuddy 能调用的工具或脚本，才能进入任务流程。

课程素材“外部 API”章主要讲模型配置。本章保留这项基础能力，并补充管理者经常遇到的业务接口协作方式。模型配置官方说明与连接器开发官方说明分别介绍这两类接入。

一、通过界面添加模型 API ​

第一步：向服务提供方拿齐四项信息 ​

字段具体含义应向谁核对
提供商或套餐类型普通 API、Coding Plan、Token Plan 等入口采购记录或服务商控制台；同一家厂商的不同套餐也可能使用不同地址
接口地址客户端向哪里发送模型请求服务商提供的 WorkBuddy／OpenAI 兼容接入说明
模型名称／模型 ID实际调用哪个模型当前 Key 有权使用的模型列表；显示名称与接口 ID 可能不同
API Key调用凭据自己有权限访问的服务商控制台；课堂演示使用占位符

练习用 YOUR_API_KEY 代替真实密钥。正式配置时在本机输入框填写，课程截图、共享任务单和导出的日志中只保留遮蔽后的标识。企业账户可能由管理员限制自定义模型入口；遇到入口缺失，核对账户策略和客户端版本。企业模型管理说明

第二步：打开“模型”，选择“添加模型” ​

从账户菜单进入设置，在左侧选择“模型”，找到自定义模型区域。先看当前是否已经存在可用配置，已有的企业配置可直接选择。

图 F05-1设置 → 模型 → 添加模型
设置 → 模型 → 添加模型
看哪里：左侧“模型”和右侧“添加模型”；弹窗有提供商、API Key、模型名称。
怎么做：按自己已开通的服务选择提供商；本次练习先辨认字段，未提供真实 Key 时不要把空配置当作接入成功。来源：WorkBuddy 官方「模型配置」，2026-09-17 核对。官方示例图，产品版本与按钮位置可能变化；图中套餐、模型和示例资料以实际账户为准。 点击图片可放大。

第三步：选对服务入口，再填写字段 ​

提供商列表通常会区分套餐与普通 API。列表里能看到某家厂商，只说明客户端有相应入口；账号额度、可用模型仍以你的服务账户为准。核对完成后保存。

图 F05-2分辨套餐入口与普通 API 入口
分辨套餐入口与普通 API 入口
看哪里：提供商列表中的 Token Plan、Coding Plan、自定义 API 分组。
怎么做：对照采购或开通的产品选择分组，避免把普通 API Key 填入另一种套餐。来源：WorkBuddy 官方「模型配置」，2026-09-17 核对。官方示例图，产品版本与按钮位置可能变化；图中套餐、模型和示例资料以实际账户为准。 点击图片可放大。

若服务不在预设列表里，选择“自定义／Custom”。高级选项中的工具调用、图片输入和推理能力，应按服务文档与实际测试填写；勾选选项本身不会让模型获得该能力。

图 F05-3自定义服务：地址、Key 和模型 ID 分别填写
自定义服务：地址、Key 和模型 ID 分别填写
看哪里：接口地址、API KEY、模型名称，以及下方高级配置。
怎么做：地址与路径按服务商给的完整示例核对，尤其检查 /v1 和 /chat/completions 是否重复；不要照抄图中的示例域名。来源：WorkBuddy 官方「模型配置」，2026-09-17 核对。官方示例图，产品版本与按钮位置可能变化；图中套餐、模型和示例资料以实际账户为准。 点击图片可放大。

第四步：回到新任务，做一个可验收的小测试 ​

在任务输入框附近的模型选择器中选择刚添加的模型，先提交简短文字，再测试工作中需要的文件与工具能力。下面这段不需要真实业务资料。

text
这是接入验证，请仅处理下列模拟数据：
项目C，2026年8月，签约目标12000万元，实际9600万元。
先列出你实际收到的四项信息，再计算完成率和差额。
如当前环境支持文件工具，将结果保存为“接入验证_项目C.md”；
若无法使用文件工具，明确说明，不能仅在回复中声称已经保存。

应得到完成率 80%、差额 2,400 万元。回到输出目录确认文件存在并打开检查。文字能回复，只能证明基础对话链路可用；读取文件、调用工具、处理图片需要分别测试。接入第三方模型后的费用和数据处理规则随相应服务走。企业模型管理中的使用说明

本地模型也有独立的接入条件 ​

官方提供 Ollama 入口。本地服务需先运行，模型需已下载且名称正确，电脑内存与计算能力也要足够。若本地服务没有启动，填写地址后仍然无法使用。课程不代替学员安装模型；有本地部署需求时，由技术同事先完成服务与能力验证。

图 F05-4Ollama：先运行本地服务，再连接
Ollama：先运行本地服务，再连接
看哪里：提供商“Ollama 本地”、localhost:11434 接口、模型名称字段。
怎么做：由已完成本地部署的同事确认服务地址和实际模型名，再用上方小测试验收；采用远程地址时另行确认服务所在机器。来源：WorkBuddy 官方「模型配置」，2026-09-17 核对。官方示例为本机 localhost 服务。界面可能更新；本地模型之外的联网搜索、云端资料库与连接器仍有各自的数据流向。 点击图片可放大。

二、把外部业务 API 变成可调用能力 ​

第一步：先写明业务需求，再索取接口文档 ​

不要只给技术同事一句“把系统接入 AI”。用下面这张任务单，先将目标缩到一个项目、一个月、一个查询。

项目本课模拟填写
要办的事查询项目 C 的 2026-08 签约目标与实际
返回后用于什么月度事实表与 PPT 第 4 页
所需字段项目编号、期间、指标、目标、实际、单位、数据更新时间、记录 ID
服务环境测试环境；先只读查询
当前成功标准一条记录可解释，数字与原系统一致，单位明确
后续批量范围小样通过后，再扩到已授权项目和月份

拿到文档后核对：请求方式、地址、鉴权、输入参数、响应字段、分页、错误码和频率限制。这些信息缺哪项，就向系统负责人问哪项。不能从网页能登录推断接口已开放，也不能从接口返回了空列表推断项目没有业务。

第二步：读懂一次请求和一次响应 ​

下列请求与响应均为教学模拟，域名 example.invalid 无法作为生产服务使用，字段也不代表大华现有系统。

http
GET https://example.invalid/api/v1/project-monthly?project_id=C&period=2026-08
Authorization: Bearer YOUR_API_KEY
Accept: application/json

GET 表示此次按参数读取；project_id 和 period 限定查询范围；请求头中的令牌让服务识别调用者。真实服务也可能采用 OAuth、签名或其他鉴权方式，必须按它的文档执行。

json
{
  "request_id": "DEMO-202608-C-001",
  "code": "OK",
  "data": [{
    "project_id": "C",
    "period": "2026-08",
    "metric": "signed_amount",
    "target": 12000,
    "actual": 9600,
    "unit": "万元",
    "record_id": "C-SAL-0801",
    "updated_at": "2026-09-02"
  }],
  "has_more": false
}

读响应时先看业务状态，再看记录与范围，最后才做计算。请求返回成功状态后，仍需确认 code、空值、单位和分页；一页数据无法代表全部项目。

第三步：让 WorkBuddy 先分析文档与模拟响应 ​

text
我准备对接一个项目月度查询接口。请先分析我提供的接口文档和模拟响应。
先输出“已知字段／待确认字段／鉴权方式／返回结构／分页规则”五项说明。
用模拟响应生成事实表，包含来源记录ID、项目、月份、目标、实际、单位、
完成率、差额和数据更新时间。暂不发送任何网络请求。
再生成一份调用脚本草稿，密钥从环境变量读取，日志不打印密钥。
真实地址、模型或服务字段未确认时，保留占位符并明确列出待补项。

这一步先验证业务理解。代码草稿中的字段要与接口文档逐项对照，不能把模拟字段直接套进真实系统。

第四步：选接入形式，小样通过后再批量 ​

已有官方或企业连接器时，按连接器说明完成登录和工具核验；已有 HTTP API 时，可由技术同事封装成 MCP 工具或可复用脚本。WorkBuddy 官方开发文档区分 MCP 与 CLI 接入方式，实际采用哪种取决于系统现有能力。连接器接入方式

真实测试的顺序：查询一条 → 对照源系统 → 检查完整字段 → 读取一页 → 验证分页与重复 → 扩到目标范围。有创建、修改、发送行为的接口，再增加“目标对象、变更内容、重复执行结果”的核验。重试前先查上次是否已经成功，避免生成重复单据。

三、失败时应当看什么 ​

表现优先查看管理者应要求的说明
401／鉴权失败Key 是否有效、请求头是否正确、是否用错环境哪一步未通过，不展示完整 Key
403／没有权限账号范围、企业策略、项目授权缺少哪个资源或动作的权限
404／模型或接口不存在地址、路径、模型 ID、资源 ID实际使用的地址与文档哪里不同
参数错误／格式错误必填字段、类型、日期格式、请求方法哪个字段值不符合要求
429／限流或额度提示服务方错误说明、并发、配额等待、减小批量或补充额度的具体依据
超时／5xx网络与服务状态、请求耗时已完成多少、未完成多少、重试是否会重复写入
返回空数据项目编号、月份、分页与账号范围区分“查无记录”“条件错”“无权限”“读取失败”

状态码只帮助定位，最终要结合服务方错误正文。HTTP 基本语义可参照 RFC 9110；额度和业务错误码由各服务自行定义。

text
请解释刚才的失败：列出发生在哪一步、已确认的事实、仍待核的原因、
下一步最小验证动作。保留请求ID和脱敏错误信息，不输出密钥。
不要把失败记录从最终汇总中删除；把它们单独列为“未取得数据”。

本节验收 ​

  • 能分别说明“调用哪个模型”和“连接哪个业务系统”。
  • 能指出地址、模型或资源 ID、鉴权字段各自的作用。
  • 模型小测试算出 80% 与 2,400 万元；如声称生成文件，可实际打开。
  • 业务接口练习保留项目、期间、单位、记录 ID 与数据更新时间。
  • 没有真实服务的学员交付配置核对表与模拟验收表，并将连通状态标成“待现场验证”。

继续学习：基础 06｜ima 知识库：从入库到有出处的汇报底稿。