使用集成调用 OpenAI 模型

连接 OpenAI 集成之后，Func 里用 ctx.ai.openai 就能调模型：对话、翻译、抽取结构化数据、调用一次工具、生成图片。API Key 只保存在服务端，代码里不会出现。

连接 OpenAI

打开编辑器的后端 → 集成，点 OpenAI，按下表填写。保存时平台会真的打一次上游，密钥不对当场报错，而不是等到有人用到这个功能才发现。

chat：一次对话

ctx.ai.openai.chat(params) 发一次调用并返回完整结果。

export function translate(input, ctx) {
  const r = ctx.ai.openai.chat({
    messages: [
      { role: 'system', content: '把用户输入翻译成英文，只输出译文' },
      { role: 'user', content: input.text },
    ],
    model: 'gpt-4o-mini',   // 不传就用集成里配的默认模型
    temperature: 0.2,
    maxTokens: 512,
  })
  return { text: r.content, tokens: r.totalTokens }
}

返回：

要 JSON 就传 json: true

让模型输出 JSON 是这个能力最常见的用法：翻译、抽取、分类全是。json: true 时平台会剥掉模型爱包的代码块再解析，结果放在 data 里。

export function extract(input, ctx) {
  const r = ctx.ai.openai.chat({
    messages: [{ role: 'user', content: `从这段话里抽出姓名和城市，返回 JSON：${input.text}` }],
    json: true,
  })
  return { name: r.data.name, city: r.data.city }
}

单次 tool call

传 tools，模型要调工具时 toolCalls 里就有东西。典型用法是一轮：把用户的自然语言变成一次结构化的函数调用，站点自己执行，然后直接回话。

export function assistant(input, ctx) {
  const r = ctx.ai.openai.chat({
    messages: [{ role: 'user', content: input.text }],
    tools: [{
      type: 'function',
      function: {
        name: 'reschedule',
        description: '把一个会议改期',
        parameters: {
          type: 'object',
          properties: { meetingId: { type: 'string' }, date: { type: 'string' } },
          required: ['meetingId', 'date'],
        },
      },
    }],
    toolChoice: 'auto',
  })

  if (r.toolCalls?.length) {
    const c = r.toolCalls[0]
    // c.arguments 已经是对象
    ctx.db.update('meetings', c.arguments.meetingId, { date: c.arguments.date })
    return { done: true }
  }
  return { reply: r.content }
}

想跑第二轮（执行完工具再让模型总结）也可以，把工具结果拼回 messages 再调一次即可：

const r2 = ctx.ai.openai.chat({
  messages: [
    { role: 'user', content: input.text },
    { role: 'assistant', toolCalls: r.toolCalls },              // 回放模型上一轮的要求
    { role: 'tool', toolCallId: r.toolCalls[0].id, content: JSON.stringify(result) },
  ],
})

平台不替你跑这个循环：几轮停、工具能不能读数据库、超时怎么算，只有站点自己知道。

生成图片

ctx.ai.openai.image(params)。强烈建议带 upload: true，图片会直接存进项目自己的空间并返回永久地址。

export const config = { timeoutMs: 120000 }   // 生图慢，几十秒是常态

export function cover(input, ctx) {
  const r = ctx.ai.openai.image({
    prompt: input.prompt,
    size: '1024x1024',
    quality: 'high',
    upload: true,
  })
  return { url: r.images[0].fileUrl }
}

返回 { model, images: [...] }，每张图是 { fileUrl | imageBase64, mimeType, bytes, revisedPrompt? }。

逃生舱：extra 与 call

想传平台没暴露的字段，用 extra。它原样并进请求体，但改不坏 messages：

ctx.ai.openai.chat({
  messages,
  extra: { top_p: 0.9, seed: 42, response_format: { type: 'json_object' } },
})

想调 /chat/completions 之外的接口，用 call(path, body)。请求体原样发出，上游返回的 JSON 原样交回，密钥同样不进沙箱：

const r = ctx.ai.openai.call('/embeddings', {
  model: 'text-embedding-3-small',
  input: input.text,
})
const vector = r.data[0].embedding

多渠道：via(tag)

一个项目可以接多份 OpenAI 配置，比如分类用便宜模型、写作用强模型，或者一份官方一份自建网关。给每份配置写上渠道标签，代码里用 via() 选：

ctx.ai.openai.via('cheap').chat({ messages })
ctx.ai.openai.via('strong').chat({ messages })

不写 via() 时用标签为 default 的那份。

报错怎么看

上游自己的报错（额度用完、模型不存在、速率限制）会原样带上文案转成 400 或 502。不会把上游的 401 直接抛给前端，那会让页面误以为是没登录。

不做的事

相关文档：更多集成、语音合成集成、Func 后端能力。