im.ttalk.agent.provider.common.openai-compat — im.ttalk/clj-agent-provider 0.5.447

OpenAI 兼容 API 调用

提供 OpenAI 风格 API 的通用调用代码，供多个 Provider 复用：

• OpenAI
• 智谱 AI (ZhiPu)
• Ollama
• 其他 OpenAI 兼容 API

使用示例：

(require '[im.ttalk.agent.provider.common.openai-compat :as compat])

;; 同步调用 (compat/call-api api-url api-key config messages tools)

;; 流式调用 (compat/call-api-stream api-url api-key config messages tools on-token)

build-messages clj

(build-messages system-prompt messages)

构建消息列表（含系统提示）

参数：

• system-prompt: 系统提示（可选）
• messages: 消息列表

返回： 完整消息列表

build-params clj

(build-params config messages tool-schemas)

(build-params {:keys [model max-tokens system-prompt temperature top-p stop
                      response-format frequency-penalty presence-penalty seed n
                      tool-choice user logprobs top-logprobs thinking
                      parallel-tool-calls reasoning-effort verbosity modalities
                      audio do-sample tool-stream request-id user-id
                      stream-options extra-body]
               :as config}
              messages
              tool-schemas
              stream?)

构建 API 请求参数

参数：

• config: 配置 map，支持：
  • 必需：:model
  • 采样/提示词控制：:max-tokens :temperature :top-p :stop :frequency-penalty :presence-penalty :seed :n :tool-choice :user :logprobs :top-logprobs :thinking（GLM 等支持思考开关的模型）
  • 工具调用：:tool-choice :parallel-tool-calls（并行工具调用开关）
  • 推理控制：:reasoning-effort（o 系列 / GPT-5）:verbosity（GPT-5 输出冗长度）
  • 多模态输出：:modalities（如 [text audio] 文本+语音）:audio（{:voice .. :format ..}）
  • 系统提示：:system-prompt
  • 结构化输出：:response-format（json_object 或 json_schema+strict 模式）
  • 流式用量：:stream-options（OpenAI 标准 stream_options；流式缺省 {:include_usage true}，显式 false / {} 关闭；非流式恒不发）
  • 专有参数逃生通道：:extra-body（map，直接 merge 进请求体，覆盖各家私有字段）； 要删库生成的键用 :configure-request（见 request-body / common.request-hook）
  • 统一思考档位：:thinking-effort / :thinking-enabled / :thinking-style（见 common.thinking； 显式 :thinking / :reasoning-effort 优先，原样透传）
• messages: 消息列表
• tool-schemas: 工具 schema 列表

返回： API 参数 map

说明：

• temperature/top_p 改为「存在才设」—— 不再强塞默认值（推理类模型对此敏感）。
• OpenAI 兼容协议的 prompt caching 是自动的，无需 cache_control；命中情况见 响应 usage 的 prompt_tokens_details.cached_tokens（OpenAI）/ prompt_cache_hit_tokens（DeepSeek）。

build-tool-result clj

(build-tool-result tool-id content)

构建工具结果消息

参数：

• tool-id: 工具调用 ID
• content: 结果内容

返回： tool 消息 map

call-api clj

(call-api api-url api-key config messages tools & [opts])

调用 OpenAI 兼容 API（同步）

参数：

• api-url: API 端点 URL
• api-key: API 密钥
• config: 请求配置
• messages: 消息列表
• tools: 工具列表
• opts: 可选配置 {:timeout 120000, :extra-headers {}}

返回： API 响应 map

示例： (call-api "https://api.openai.com/v1/chat/completions" "sk-xxx" {:model "gpt-4" :max-tokens 4096} [{:role "user" :content "你好"}] [])

call-api-deferred clj

(call-api-deferred api-url api-key config messages tools & [opts])

调用 OpenAI 兼容 API（异步，返回 deferred<响应体>）。

参数与语义同 call-api；失败落 error channel（canonical error）。 无重试：重试在 ChatModel 层（im.ttalk.agent.retry/run-async）。

call-api-stream clj

(call-api-stream api-url api-key config messages tools on-token & [opts])

调用 OpenAI 兼容 API（流式，同步）

参数：

• api-url: API 端点 URL
• api-key: API 密钥
• config: 请求配置
• messages: 消息列表
• tools: 工具列表
• on-token: token 回调函数 (fn [{:keys [token index accumulated]}] ...)
• opts: 可选配置 {:timeout 120000, :extra-headers {}}

返回： 与非流式调用兼容的响应格式

示例： (call-api-stream url key config messages tools (fn [{:keys [token]}] (print token) (flush)))

call-api-stream-deferred clj

(call-api-stream-deferred api-url
                          api-key
                          config
                          messages
                          tools
                          on-token
                          &
                          [opts])

流式调用（异步，返回 deferred<最终响应>）。

参数与语义同 call-api-stream（含 :retry 的建链重试与取消）， 只是不阻塞调用线程。⚠️ on-token 在传输层 executor 上派发，不是调用线程。

request-body clj

(request-body config messages tool-schemas stream?)

发出前的最终请求体：build-params → 流式补 :stream true → 宿主钩子 :configure-request（见 common.request-hook）。

四条调用路径（同步 / 流式 / 两条 deferred）都只经这里取请求体，钩子因此 只有一处、且看得见思考字段、:extra-body 与 :stream（宿主可按 stream 做各家私有规则）。