im.ttalk.agent.provider.common.base — im.ttalk/clj-agent-provider 0.5.447

OpenAI 兼容 Provider 基础模块

为所有 OpenAI 兼容的 LLM Provider 提供统一的基础实现。 支持: OpenAI, ZhiPu, Ollama, Gemini, Mistral 等。

主要功能：

• 统一的 API 调用包装
• 通用的 Provider Record 实现
• 配置管理

使用示例：

(require '[im.ttalk.agent.provider.common.base :as base])

;; 创建配置 (def config (base/make-config :openai "https://api.openai.com/v1" "OPENAI_API_KEY"))

;; 创建 Provider (def provider (base/create-provider config))

call-api clj

(call-api config llm-config messages tools)

调用 API（同步）

参数：

• config: Provider 配置 atom
• llm-config: LLM 调用配置 {:model ... :max-tokens ...}
• messages: 消息列表
• tools: 工具列表

返回： API 响应

call-api-deferred clj

(call-api-deferred config llm-config messages tools)

异步调用 API（返回 deferred<响应体>）——call-api 的孪生。

2026-09-03 取代了旧的 callback 式 call-api-async：那套零调用点、把裸 HTTP map 交给回调、绕过 wire 转换与归一化，接不进 filter 链 （docs/async-chat-model-design.md §0）。

call-api-stream clj

(call-api-stream config llm-config messages tools on-token)

流式调用 API（同步）

参数：

• config: Provider 配置 atom
• llm-config: LLM 调用配置
• messages: 消息列表
• tools: 工具列表
• on-token: Token 回调函数

返回： 最终完整响应

call-api-stream-deferred clj

(call-api-stream-deferred config llm-config messages tools on-token)

异步流式调用 API（返回 deferred<最终响应>）——call-api-stream 的孪生。

create-provider clj

(create-provider config)

从配置创建 Provider

参数：

• config: Provider 配置 atom

返回： OpenAICompatProvider 实例

create-provider-with-opts clj

(create-provider-with-opts config opts)

创建 Provider 并应用额外选项

参数：

• config: 默认配置 atom（共享的 provider 默认值，只读快照）
• opts: 额外选项（每实例独立，如 :api-key / :base-url）

返回： OpenAICompatProvider 实例

注意：每个实例持有从默认值快照 + opts 派生的独立 config atom， 绝不就地 mutate 共享的全局默认 atom——否则多实例（多租户 / 多 key / 主备 key）会互相覆盖、并发创建有竞态。

defprovider clj macro

(defprovider provider-name
             &
             {:keys [base-url env-key endpoint timeout default-model api-key
                     require-api-key? require-model?]
              :or {endpoint "/chat/completions" timeout 120000}})

定义 OpenAI 兼容的 Provider —— 一处声明，消除各 provider 重复样板。

必需：

• :base-url API 基础 URL
• :env-key API Key 的环境变量名

可选：

• :endpoint API 端点路径（默认 "/chat/completions"）
• :timeout 请求超时毫秒（默认 120000）
• :default-model 默认模型名
• :api-key 预置 API Key（如本地 Ollama 用 "ollama"）
• :require-api-key? 创建时校验 api-key 非空，缺失抛错（gemini/mistral）
• :require-model? 创建时校验 :model 必填，缺失抛错（ollama）

用法： (defprovider openai :base-url "https://api.openai.com/v1" :env-key "OPENAI_API_KEY" :default-model "gpt-4")

生成：default-config、call-<name>{,-stream,-async,-stream-async}、create-provider。

get-api-key clj

(get-api-key config)

获取 API Key

优先使用配置中的值，否则从环境变量读取

get-api-url clj

(get-api-url config)

构建完整 API URL

将 base-url 和 endpoint 拼接为完整的 API 请求地址。 去除 base-url 尾部斜线以避免重复。

参数：

• config: Provider 配置 atom

返回： 完整的 API URL 字符串

make-config clj

(make-config provider-name
             base-url
             env-key
             &
             {:keys [endpoint timeout default-model]
              :or {endpoint "/chat/completions" timeout 120000}})

创建 Provider 配置

参数：

• provider-name: Provider 名称 (keyword)
• base-url: API 基础 URL（不含 endpoint 路径）
• env-key: API Key 的环境变量名

可选参数：

• :endpoint API 端点路径 (默认 "/chat/completions")
• :timeout 请求超时 (毫秒, 默认 120000)
• :default-model 默认模型名称

返回： 配置 atom

update-config! clj

(update-config! config opts)

更新配置

参数：

• config: 配置 atom
• opts: 要合并的选项

返回： 更新后的配置值