# 性能优化建议

在此模式下,每一次原子接口调用都对应一段完整的「模型决策 → 端侧执行 → 结果回流 → 再次推理」往返,通常会带来 1~2 秒的额外耗时。在不调整模型与提示词的前提下,合理设计原子接口即可显著降低响应时延。

本文给出四项优化手段,按改造成本由低到高排列:

优化手段 优化对象 前置条件
输出精简 每段往返的输入规模 无,建议所有 SKILL 均执行
apiCalls 链式调用 往返次数 下游接口的触发与入参可由上游返回结果确定
公共逻辑下沉为中间件 往返次数 逻辑为多接口公共前置或后置,且幂等
绑定接口合并 往返次数 两个接口必然成对且有序出现

其中,输出精简降低的是每段往返的输入量,后三项减少的是往返段数。建议按上述顺序逐项评估。

# 一、输出精简

# 1.1 适用场景

structuredContent 同时面向两类消费者:小程序 AI(理解与推理)与端侧(原子组件渲染、接力)。仅供端侧使用、模型决策用不到的字段——如页面跳转路径、样式与埋点参数、大段枚举码表等——应从 structuredContent 中移出。

原子接口的返回结果会作为历史消息进入后续所有推理,因此该项优化的收益不限于单次调用:它缩减的是当前会话后续每一次调用的输入规模;同时上下文增长变慢,可降低上下文压缩的触发频率,使模型更长时间保有原始对话细节。

# 1.2 字段分工

字段 是否进入模型上下文 用途
content / structuredContent / isError 是 供模型理解与推理
handoff 否 接力数据,由小程序页面通过 ft.onAgentHandoff 获取

字段语义详见 接入方式 - 原子接口实现。

# 1.3 注意事项

  • 标记为 format: "page-link" 的混排链接字段必须保留在 structuredContent 中,平台需从中抽取页面路径;
  • 不建议将后端接口返回的数据不加筛选地直接写入 structuredContent。

# 二、apiCalls 链式调用

# 2.1 适用场景

当原子接口 A 执行后大概率紧接着调用原子接口 B(例如过半的 A 调用后紧跟 B),且 B 是否触发、入参取值均可由 A 的返回结果确定时,应在 A 的返回值中携带 apiCalls,由框架直接发起 B 的调用,跳过其间的一段模型推理。

# 2.2 声明方式

// 接口 A 的返回值
{
  isError: false,
  content: [{ type: 'text', text: '查询完成' }],
  apiCalls: [{ name: 'B', arguments: { id: result.id } }]
}

# 2.3 示例

仅当天气查询结果中包含台风信息时才需续调台风接口,触发条件完全由返回结果决定:

// getDailyWeatherForecast 的返回处理
const result = await fetchDailyForecast(location, days);
const resp = {
  isError: false,
  content: [{ type: 'text', text: summarize(result) }],
  structuredContent: result
};
// 仅在返回中包含台风信息时下发 apiCalls
if (result.typhoonWarning != null) {
  resp.apiCalls = [{
    name: 'getTyphoonWarning',
    arguments: { location, typhoonName: result.typhoonWarning.name }
  }];
}
return resp;

# 2.4 注意事项

  • 按条件下发:仅在返回结果满足条件时携带 apiCalls,不应无条件下发;
  • 依赖用户自由选择的下游接口不适用:B 的触发必须能由 A 的返回结果确定性推出;
  • apiCalls 不等同于接口合并:A、B 仍是两个独立接口,其他链路仍可单独调用 B。

# 三、公共逻辑下沉为中间件

# 3.1 适用场景

同时满足以下全部条件的接口,应从 mcp.json 的原子接口列表中移除,改为通过 skill.use() 注册为中间件:

  • 不构成独立的业务目标,用户不会专门为其发起请求;
  • 其返回值仅作为后续调用的门禁或上下文,如登录态、定位、隐私授权、统一展示卡片;
  • 是 SKILL 内多数接口的公共前置或公共后置逻辑。

若保留为原子接口,模型每轮都需先决策并调用一次,额外引入一段完整往返。

# 3.2 示例

const skill = ft.modelContext.createSkill(skillPath);
skill.use(async (ctx, next) => {
  // 前置逻辑:每次原子接口调用前自动执行
  const token = ft.getStorageSync('token');
  if (!token) {
    const { code } = await ft.login();
    const res = await ft.request({ url: '.../login', data: { code } });
    ft.setStorageSync('token', res.data.token);
  }
  try {
    await next(); // 执行实际的原子接口
  } finally {
    // 后置逻辑:日志上报、统一展示等
  }
});

中间件的完整语义详见 接入方式 - 中间件机制。

# 3.3 注意事项

  • 中间件须保持幂等、无副作用,其在每次原子接口调用前后均会执行;
  • 整个中间件链与原子接口执行时间共享同一超时上限,中间件内不应引入长耗时逻辑;

# 四、绑定接口合并

# 4.1 适用场景

两个原子接口必然成对出现且调用顺序固定时,应合并为一个接口。

# 4.2 示例

以一段输入前置处理为例:原设计包含 checkContent(内容安全校验与登录检查)与 intentRecognition(意图识别)两个原子接口,两者入参均为用户原始输入,且逻辑上始终成对出现、不会单独被调用。此类绑定关系应合并为单一接口:

// 合并前:每轮用户输入,模型需连续调用两次
// checkContent({ content, business }) -> intentRecognition({ query })

// 合并后:一次调用同时返回校验结果与识别意图
skill.registerAPI('preprocess', async ({ content, business }) => {
  const check = await checkContentSafety(content); // 原 checkContent 的逻辑
  if (!check.passed) {
    return {
      isError: false,
      content: [{ type: 'text', text: check.reason }],
      structuredContent: { passed: false }
    };
  }
  if (check.needLogin) {
    // 未登录分支保持原有处理:由 apiCalls 直连登录卡片,不经模型推理
    return {
      isError: false,
      content: [{ type: 'text', text: '请先登录' }],
      structuredContent: { passed: false, needLogin: true },
      apiCalls: [{ name: 'authLogin', arguments: { originQuery: content } }]
    };
  }
  const intent = await recognizeIntent(content); // 原 intentRecognition 的逻辑
  return {
    isError: false,
    content: [{ type: 'text', text: '前置校验通过' }],
    structuredContent: { passed: true, needLogin: false, intent }
  };
});

合并后,每轮用户输入由 2 次接口调用(2 段模型推理)减少为 1 次。

# 4.3 不适用的情形

  • 链路中间存在用户决策点,如选择门店、选择商品、确认订单——合并将剥夺用户的选择权;
  • 仅为高频共现而非绑定关系——此类场景应使用 apiCalls,不应强行合并。
© FinClip with ❤ , Since 2017