im.ttalk.agent.provider.api — im.ttalk/clj-agent-provider 0.5.447

LLM 模块统一 API 入口

提供所有 LLM 功能的统一访问入口。

主要功能：

• Provider 创建和管理
• LLM 调用（同步、流式、异步）
• 响应解析
• 错误处理

使用示例：

(require '[im.ttalk.agent.provider.api :as llm])

;; 创建 Provider (def provider (llm/create-provider :openai))

;; 同步调用 (llm/call provider config messages tools)

;; 流式调用 (llm/call-stream provider config messages tools on-token)

;; 提取结果 (llm/extract-text provider response) (llm/extract-tool-calls provider response)

assistant-message clj

创建助手消息（中立格式 {:role :assistant ...}）

audio-part clj

音频部件（OpenAI 兼容端点只收内联 wav/mp3）

build-tool-result clj

(build-tool-result provider tool-id content)

构建工具结果消息

参数：

• provider: Provider 实例
• tool-id: 工具调用 ID
• content: 结果内容

返回： 工具结果消息

call clj

(call provider config messages)

(call provider config messages tools)

调用 LLM（同步）

参数：

• provider: Provider 实例
• config: 配置 {:model "..." :max-tokens n ...}
• messages: 消息列表 [{:role "user" :content "..."}]
• tools: 工具列表（可选）

返回： API 响应

示例： (call provider {:model "gpt-4" :max-tokens 4096} [{:role "user" :content "你好"}])

call-stream clj

(call-stream provider config messages tools on-token)

流式调用 LLM

参数：

• provider: Provider 实例
• config: 配置
• messages: 消息列表
• tools: 工具列表
• on-token: 回调函数 (fn [{:keys [token index accumulated]}] ...)

返回： 最终完整响应

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

content-text clj

取 content 的纯文本（字符串原样 / 部件向量取文本部件拼接）

create-embedding-provider clj

创建 embedding provider

(create-embedding-provider :openai) (create-embedding-provider :openai-compat {:base-url "..." :api-key "..." :model "bge-m3"})

create-provider clj

(create-provider provider-type)

(create-provider provider-type opts)

创建 LLM Provider

参数：

• provider-type: Provider 类型 (:openai :anthropic :zhipu :ollama :gemini :mistral :mock)
• opts: 配置选项（可选）

返回： Provider 实例

示例： (create-provider :openai) (create-provider :anthropic {:api-key "sk-..."})

create-provider-auto clj

(create-provider-auto provider-type)

(create-provider-auto provider-type opts)

自动创建 Provider（从环境变量和配置合并）

参数：

• provider-type: Provider 类型
• opts: 用户配置（可选）

返回： Provider 实例

embed clj

批量文本向量化 → {:embeddings [[..] ..] :model .. :usage .. :provider ..}

embed-one clj

单条文本向量化 → 向量

error clj

创建错误

error? clj

检查是否为错误

extract-text clj

(extract-text provider response)

从响应中提取文本

参数：

• provider: Provider 实例
• response: API 响应

返回： 文本字符串

extract-tool-calls clj

(extract-tool-calls provider response)

从响应中提取工具调用

参数：

• provider: Provider 实例
• response: API 响应

返回： 工具调用列表 [{:id "..." :name "字符串" :args {...}}]

file-part clj

文件部件（PDF 等；内联数据须给 :media-type）

get-input-tokens clj

获取输入 token 数量

get-output-tokens clj

获取输出 token 数量

get-total-tokens clj

获取总 token 数量

image-part clj

图片部件（URL / data URI / base64+:media-type / byte[] / java.io.File）

(image-part "https://example.com/a.png") (image-part (clojure.java.io/file "a.png")) (image-part base64-str {:media-type "image/png"})

make-response clj

创建统一响应结构

参数（关键字）：

• :text 文本内容
• :tool-calls 工具调用列表
• :usage token 使用情况（自动归一化）
• :finish-reason 完成原因（自动归一化）
• :model 模型名称
• :id 响应 ID
• :provider Provider 类型
• :raw-response 原始响应

返回： ChatResponse record（实现 ILLMResponse 协议）

make-tool-call clj

创建工具调用结构（v0.2 起与中立消息 tool-call 同构）

参数：

• id: 工具调用 ID
• name: 工具名称（keyword/字符串，规范化为字符串）
• args: 工具参数 map

返回： {:id "..." :name "字符串" :args {...}}

normalize-finish-reason clj

归一化完成原因

将不同 Provider 的完成原因统一为标准关键字： :stop | :tool-use | :max-tokens | :content-filter | :unknown

示例： (normalize-finish-reason "tool_calls") ; => :tool-use (normalize-finish-reason "end_turn") ; => :stop

normalize-usage clj

归一化 Token 使用情况

将 OpenAI/Anthropic 的不同命名统一为标准格式： {:input-tokens n :output-tokens m :total-tokens t}

示例： (normalize-usage {:prompt_tokens 100 :completion_tokens 50}) ; => {:input-tokens 100 :output-tokens 50 :total-tokens 150}

provider-name clj

(provider-name provider)

获取 Provider 名称

retryable? clj

(retryable? err)

检查错误是否可重试

stopped-by-max-tokens? clj

检查是否因达到最大 token 而停止

stopped-by-tool-use? clj

检查是否因工具调用而停止

stopped-normally? clj

检查是否正常停止

supported-embedding-providers clj

支持 embedding 的内置 provider 列表

supported-providers clj

(supported-providers)

获取支持的 Provider 列表

supports-embedding? clj

(supports-embedding? p)

该实例是否支持 embedding（可信探测：IEmbeddingProvider 无 Object 兜底）

supports-function-calling? clj

(supports-function-calling? provider)

检查是否支持函数调用

supports-stream? clj

(supports-stream? provider)

检查是否支持流式调用

system-message clj

创建系统消息（中立格式 {:role :system ...}）

text-part clj

文本部件 {:type :text :text "..."}

tool-message clj

创建工具结果消息（中立格式 {:role :tool :tool-call-id ...}；参数 [id name content]）

user-message clj

创建用户消息（中立格式 {:role :user ...}）

with-error-handling clj

安全执行函数