LLMs 大语言模型封装¶

LLMs 模块是 TFRobot 大脑系统的核心组件，负责统一封装各大 LLM 提供商的 API，提供一致的调用接口和数据结构。作为"仿生机器人"的思维中枢，LLM 模块承载着将用户输入转化为智能决策的关键职责。

设计理念¶

为什么需要 LLMs 模块¶

在构建 AI 智能体时，直接调用各厂商的 LLM API 会面临以下挑战：

API 差异巨大：OpenAI、Anthropic、Google 等厂商的接口设计、参数名称、响应格式各不相同
计费统计困难：不同厂商的计费方式（按 token、按请求）、价格单位不统一
错误处理复杂：上下文超长、网络超时、API 限流等错误的处理逻辑因厂商而异
多模态支持不一：图片、视频、音频、PDF 等多模态输入的处理方式各不相同
工具调用格式不同：Function Calling 的实现方式和数据结构差异显著

LLMs 模块通过抽象基类 + 具体实现的设计模式，屏蔽了这些差异，让上层应用可以专注于业务逻辑，而非底层 API 细节。

核心设计决策¶

1. 三层架构¶

BaseLLM (抽象基类)
├── ChatLLM (对话模型抽象)
│   ├── GPT (OpenAI 实现)
│   ├── Claude (Anthropic 实现)
│   ├── Gemini (Google 实现)
│   └── ...
└── GenerationLLM (生成模型抽象)
    └── DeskLLM (桌面环境模拟)
        ├── GPTDesk
        ├── ClaudeDesk
        └── ...

BaseLLM：定义通用接口和核心功能（token 计算、上下文压缩、遥测追踪）
ChatLLM：对话式模型，适合多轮对话、工具调用场景
GenerationLLM：生成式模型，适合连续文本生成（DSL、代码编辑等）

2. 统一消息结构¶

使用 TFRobot 内部的 BaseLLMMessage 类型，通过 reformat_request_msg_to_api 方法转换为各厂商所需的格式。

3. 智能上下文管理¶

当上下文超出限制时，自动触发压缩流程： 1. 使用 Splitter 预压缩（快速机械压缩） 2. 调用 LLM 智能压缩（语义保留压缩） 3. 递归衰减目标大小，最多重试 5 次

4. 多模态支持¶

统一支持图片、视频、音频、PDF 等多模态输入，自动计算 token 消耗，支持瓦片缓存。

5. 遥测集成¶

自动通过 OpenTelemetry 记录 LLM 调用的开始、结束、异常等事件，便于追踪和调试。

核心概念¶

Prompt 位置系统¶

ChatLLM 将 Prompt 分为 5 个位置，精确控制插入位置：

位置	说明	典型用途
`system_msg_prompt`	插入所有消息顶部	系统角色、工具描述、知识库
`before_input_msg_prompt`	插入当前输入之前	任务说明、上下文背景
`after_input_msg_prompt`	插入当前输入之后	输出格式要求、约束条件
`after_intermediate_msg_prompt`	插入中间消息之后	追加指令、工作流程引导
`reformat_input_prompt`	重新格式化用户输入	输入转换、预处理

工具调用模式¶

支持三种工具调用模式：

原生模式：使用厂商提供的 Function Calling API（OpenAI、Anthropic 等）
DSL 模式：通过 DSLToolPrompt 将工具转换为 DSL 语法，适合不支持工具调用的模型
TFL 模式：简化 DSL 配置，自动生成工具描述和示例

响应格式¶

支持三种响应格式：

text：纯文本返回
json_object：JSON 返回，不限制结构
json_schema：JSON 返回，严格符合指定 Schema

配置参数¶

通用参数¶

参数	类型	说明	默认值
`name`	`str`	模型名称，需全局唯一（如 `gpt-4o`）	-
`input_price`	`float`	输入价格，单位为元/kTokens	`0.0`
`output_price`	`float`	输出价格，单位为元/kTokens	`0.0`
`context_window`	`int`	上下文窗口大小（tokens）	根据模型自动获取
`response_format`	`LLMResponseFormat`	响应格式配置	`text`
`tool_filter`	`str`	工具过滤表达式（如 `(&(Edit)(!(IDEWrite)))`）	`None`
`locale`	`Locale`	内部提示语言（影响压缩提示等）	`DEFAULT`

ChatLLM 专用参数¶

参数	类型	说明	默认值
`system_msg_prompt`	`list[BasePrompt]`	系统消息提示列表	`[]`
`before_input_msg_prompt`	`list[BasePrompt]`	用户输入前提示列表	`[]`
`after_input_msg_prompt`	`list[BasePrompt]`	用户输入后提示列表	`[]`
`after_intermediate_msg_prompt`	`list[BasePrompt]`	中间消息后提示列表	`[]`
`reformat_input_prompt`	`list[BasePrompt]`	重新格式化输入提示列表	`[]`

提供商特定参数¶

不同提供商有额外的配置参数，详见各提供商文档。

Thinking 模式（思考模式）¶

Thinking 模式允许查看大语言模型的推理过程，对于需要深度推理的任务特别有用。

支持情况¶

提供商	支持情况	实现方式	典型模型
Anthropic	✅ 原生支持	Extended Thinking	claude-3-5-sonnet-20241022
Google	✅ 原生支持	Thinking Mode	gemini-2.0-flash-exp, gemini-2.5-pro
智谱 AI	✅ 原生支持	Deep Thinking	glm-4-0520, glm-4.5
OpenAI	❌ 不支持	-	-
DeepSeek	❌ 不支持	-	-
DashScope	❌ 不支持	-	-

参数对比¶

不同提供商的参数名称和格式各不相同：

提供商	启用参数	预算参数	预算类型	额外参数
Anthropic	`enable_reasoning` (bool)	`reasoning_budget_tokens`	int，最小 1024	-
Google	-	`thinking_budget`	int/"low"/"high"	`include_thoughts` (bool)
智谱 AI	`thinking` (dict)	-	-	`{"type": "enabled"}`

配置示例¶

Anthropic Claude¶

from tfrobot.brain.chain.llms import Claude

llm = Claude(
    name="claude-3-5-sonnet-20241022",
    enable_reasoning=True,           # 启用推理
    reasoning_budget_tokens=10000,   # 设置预算
)

Google Gemini¶

from tfrobot.brain.chain.llms import Gemini

llm = Gemini(
    name="gemini-2.0-flash-exp",
    thinking_budget=10000,      # 或 "low" / "high"
    include_thoughts=True,      # 是否在输出中包含思考过程
)

智谱 AI GLM¶

from tfrobot.brain.chain.llms import GLM

llm = GLM(
    name="glm-4-0520",
    thinking={"type": "enabled"},
)

模型版本差异¶

即使是同一个提供商，不同模型版本对 thinking 模式的支持也可能不同：

Gemini 模型版本差异¶

模型	budget 范围	特殊值说明
gemini-2.5-pro	128-32768 或 -1	-1 表示自动
gemini-2.5-flash	0-24576 或 -1	0 表示关闭
gemini-2.5-flash-lite	512-24576 或 0 或 -1	0 关闭，-1 自动
gemini-2.0-flash-exp	0-24576 或 -1	0 关闭，-1 自动

注意：TFRobot 会自动验证参数范围，超出范围会抛出 ValueError。

机制说明¶

模型能力检测¶

TFRobot 使用 whosellm.LLMeta 自动检测模型是否支持 thinking 模式：

from whosellm import LLMeta

llm_meta = LLMeta("claude-3-5-sonnet-20241022")
if llm_meta.capabilities.supports_thinking:
    print("该模型支持 thinking 模式")

API 映射¶

TFRobot 参数会自动转换为各提供商的 API 格式：

# Anthropic API
{
    "thinking": {"type": "enabled", "budget_tokens": 10000}
}

# Gemini API
{
    "thinking_spec": {
        "include_thoughts": True,
        "thinking_budget": 10000
    }
}

# 智谱 AI API
{
    "thinking": {"type": "enabled"}
}

特殊处理¶

不同提供商在 thinking 模式下有不同的限制：

Anthropic：推理模式下会自动移除 top_p 参数（API 限制）
Google：需要根据模型版本验证 thinking_budget 范围
智谱 AI：只有模型支持时才会添加 thinking 参数

响应格式¶

所有支持 thinking 模式的提供商统一将推理过程存储在 reasoning_content 字段：

result = llm.complete(current_input=user_input)

# 推理过程
print(result.generations[0].reasoning_content)

# 最终答案
print(result.generations[0].text)

Ollama 特殊处理¶

Ollama 模型（本地部署）通常在输出中包含 <thinking>...</thinking> 标签，TFRobot 会自动提取：

from tfrobot.brain.chain.llms import Ollama

llm = Ollama(name="deepseek-r1")

# 自动提取 thinking 标签内容
result = llm.complete(current_input=user_input)
print(result.generations[0].reasoning_content)  # 提取的思考内容

最佳实践¶

预算设置：根据任务复杂度合理设置预算，过低可能导致推理不充分
成本考虑：thinking 模式会增加 token 消耗，注意控制成本
调试用途：适合用于调试和解释推理过程，生产环境可选
模型选择：选择支持 thinking 模式的模型，并检查版本兼容性

运行时行为¶

完整调用流程¶

用户输入
    ↓
construct_prompt_context (构建提示上下文)
    ↓
format_to_request_msgs (格式化为请求消息)
    ↓
reformat_request_msg_to_api (转换为厂商格式)
    ↓
complete / async_complete (调用 API)
    ↓
construct_llm_result (构造结果)
    ↓
返回 LLMResult

错误处理策略¶

上下文超长：抛出 ContextTooLargeError，由 Chain 层触发 compact 流程
网络超时：使用 tenacity 重试，指数退避，最多 3 次
API 限流：自动等待后重试
其他错误：记录遥测事件，向上传播

Token 计算¶

使用 whosellm 库自动获取模型的上下文窗口和计费规则。对于多模态内容，使用厂商特定的计算方式（如 OpenAI 的瓦片计费）。

使用建议¶

模型选择¶

场景	推荐模型	原因
简单对话	GPT-4o-mini、Claude Haiku	成本低、速度快
复杂推理	GPT-4o、Claude Sonnet	推理能力强、上下文大
工具调用	GPT-4o、Claude 3.5 Sonnet	工具调用稳定性高
中文场景	DeepSeek、GLM	中文理解好
代码生成	GPT-4o、Claude 3.5 Sonnet	代码能力强
桌面自动化	DeskLLM 系列	专为桌面环境优化

Prompt 配置最佳实践¶

系统角色：使用 MemoPrompt 配合 KnowledgePrompt
工具描述：使用 ToolPrompt（原生模式）或 DSLToolPrompt（DSL 模式）
输出格式：使用 ReformatPrompt 配合 JSON Schema
多模态：使用 AdditionalInfoPrompt 添加附件信息

上下文优化¶

合理设置 context_window：避免超出模型限制
使用 conversation 参数：传递必要的历史消息
控制 elements 和 knowledge 大小：避免占用过多 token
利用 intermediate_msgs：传递工具调用中间结果

与其他模块的协作¶

与 Chain 模块¶

Chain 通过 complete 方法调用 LLM
Chain 的 compacting 状态会调用 LLM 的 collapse_context 方法
Chain 的 intermediate_msgs 会传递给 LLM

与 Prompt 模块¶

LLM 使用 Prompt 模板渲染上下文
Prompt 通过 PromptContext 访问工具、知识、文档等信息

与 Drive 模块¶

LLM 通过 Neural 系统获取 Drive 中的工具列表
LLM 将工具调用结果返回给 Chain，Chain 执行工具后更新 intermediate_msgs

与 Memory 模块¶

LLM 从 conversation 参数获取历史消息
LLM 的输出会保存到 Memory 的 Buffer Store

与 Telemetry 模块¶

LLM 自动记录调用事件到 OpenTelemetry
支持 Trace、Metrics、Logs 三种可观测性数据

支持的提供商¶

提供商	Chat 模型	Generation 模型	工具调用	多模态
OpenAI	✅	✅	✅	✅
Anthropic	✅	✅	✅	✅
Google	✅	✅	✅	✅
DeepSeek	✅	✅	✅	✅
智谱 AI	✅	✅	✅	❌
阿里云	✅	✅	✅	❌
Ollama	✅	✅	✅	⚠️

详细的使用指南和 API 参考，请参阅提供商指南。

下一步¶

核心概念¶

提供商指南 - 选择合适的 LLM 提供商
BaseLLM 基类详解 - 统一接口和核心功能
ChatLLM 对话模型 - 多轮对话、工具调用
GenerationLLM 生成模型 - 连续文本生成、DSL 生成

DeskLLM 实现指南（GenerationLLM）¶

生产级推荐¶

GeminiDesk - Google Gemini 实现
✅ 多模态任务首选，1M 上下文
✅ 国内访问相对稳定，SOCKS5 代理支持
DeepSeekDesk - DeepSeek 实现
✅ 纯文本任务推荐，中文能力强
✅ FIM 支持，价格低廉
TencentDSDesk - 腾讯混元实现
✅ 国内访问稳定，功能完善

LLMs 大语言模型封装¶

设计理念¶

为什么需要 LLMs 模块¶

核心设计决策¶

1. 三层架构¶

2. 统一消息结构¶

3. 智能上下文管理¶

4. 多模态支持¶

5. 遥测集成¶

核心概念¶

Prompt 位置系统¶

工具调用模式¶

响应格式¶

配置参数¶

通用参数¶

ChatLLM 专用参数¶

提供商特定参数¶

Thinking 模式（思考模式）¶

支持情况¶

参数对比¶

配置示例¶

Anthropic Claude¶

Google Gemini¶

智谱 AI GLM¶

模型版本差异¶

Gemini 模型版本差异¶

机制说明¶

模型能力检测¶

API 映射¶

特殊处理¶

响应格式¶

Ollama 特殊处理¶

最佳实践¶

相关文档¶

运行时行为¶

完整调用流程¶

错误处理策略¶

Token 计算¶

使用建议¶

模型选择¶

Prompt 配置最佳实践¶

上下文优化¶

与其他模块的协作¶

与 Chain 模块¶

与 Prompt 模块¶

与 Drive 模块¶

与 Memory 模块¶

与 Telemetry 模块¶

支持的提供商¶

下一步¶

核心概念¶

DeskLLM 实现指南（GenerationLLM）¶

生产级推荐¶

其他实现¶

本地测试（不推荐生产）¶

技术文档¶