Skip to content

OpenAI GPT 使用指南

OpenAI 的 GPT 系列模型是业界最强大的通用大语言模型，具有出色的推理能力、工具调用支持和多模态能力。

模型概览

推荐模型

模型 上下文 特色 适用场景
gpt-4o 128K 最新旗舰、多模态全能 通用对话、复杂推理、多模态
gpt-4o-mini 128K 快速、低成本 简单对话、快速响应
gpt-4-turbo 128K 平衡性能和成本 代码生成、数据分析
gpt-3.5-turbo 16K 极低价格 简单任务、原型开发

模型选择建议

from tfrobot.brain.chain.llms import GPT

# 通用场景（推荐）
llm = GPT(name="gpt-4o")

# 成本敏感
llm = GPT(name="gpt-4o-mini")

# 代码生成
llm = GPT(name="gpt-4-turbo")

# 简单任务
llm = GPT(name="gpt-3.5-turbo")

配置参数

核心参数

from tfrobot.brain.chain.llms import GPT

llm = GPT(
    name="gpt-4o",
    temperature=0.7,        # 0.0-2.0，控制随机性
    max_tokens=4096,         # 最大输出 tokens
    top_p=1.0,              # 0.0-1.0，核采样
    frequency_penalty=0.0,   # -2.0-2.0，重复惩罚
    presence_penalty=0.0,    # -2.0-2.0，新话题惩罚
    stream=False,            # 是否流式输出
)

API 配置

llm = GPT(
    name="gpt-4o",
    openai_api_key="sk-...",        # API 密钥（推荐使用环境变量）
    openai_api_base="https://...",  # API 基础 URL（支持代理）
    openai_organization="org-...",  # 组织 ID
    timeout=60.0,                    # 请求超时时间
    max_retries=3,                   # 最大重试次数
)

响应格式

from tfrobot.brain.chain.llms import GPT

# 纯文本
llm = GPT(name="gpt-4o", response_format={"type": "text"})

# JSON 对象（不限制结构）
llm = GPT(name="gpt-4o", response_format={"type": "json_object"})

# JSON Schema（严格结构）
llm = GPT(
    name="gpt-4o",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "response",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"}
                },
                "required": ["name", "age"]
            }
        }
    }
)

工具调用

原生模式（推荐）

OpenAI 原生支持 Function Calling，稳定性最高：

from tfrobot.brain.chain.llms import GPTWithTools
from tfrobot.brain.chain.prompt.tool_prompt import ToolPrompt
from tfrobot.drive.tool.tool import tool

@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气"""
    return f"{city} 今天晴天，温度 25°C"

llm = GPTWithTools(name="gpt-4o")
llm.system_msg_prompt = [ToolPrompt()]

result = llm.complete(
    current_input=TextMessage(content="北京今天的天气怎么样？"),
    tools=[get_weather]
)

GPT vs GPTWithTools

  • GPT：基础模型，需要手动配置 ToolPrompt
  • GPTWithTools：预配置 ToolPrompt，更方便
# 方式一：使用 GPT
llm = GPT(name="gpt-4o")
llm.system_msg_prompt.append(ToolPrompt())

# 方式二：使用 GPTWithTools（推荐）
llm = GPTWithTools(name="gpt-4o")

多模态支持

图片理解

from tfrobot.schema.message.conversation.message_dto import MultiPartMessage
from tfrobot.schema.message.msg_part import TextPart, ImagePart

msg = MultiPartMessage(content=[
    TextPart(text="这张图片里有什么？"),
    ImagePart(
        image_url=ImgUrl(url="path/to/image.jpg"),
        detail="high"  # "low" | "high" | "auto"
    ),
])

result = llm.complete(current_input=msg)

图片 Detail 级别

级别 Token 消耗 适用场景
low 85 不需要细节的场景
high 85 + 170 × 瓦片数 需要细节（OCR、图表分析）
auto 根据图片自动选择 让模型自动决定

音频处理

from tfrobot.schema.message.conversation.message_dto import AudioMessage

msg = AudioMessage(
    content=Path("path/to/audio.mp3"),
    creator=BaseUser(name="User", uid="1")
)

result = llm.complete(current_input=msg)

成本优化

Token 计费

from tfrobot.brain.chain.llms import GPT

# 设置价格（用于计费统计）
llm = GPT(
    name="gpt-4o",
    input_price=0.005,   # 5美元/百万tokens
    output_price=0.015   # 15美元/百万tokens
)

节省 Token 的技巧

  1. 使用摘要模式：历史消息自动摘要
  2. 控制知识库大小：截断过长的 knowledge
  3. 合理设置 max_tokens：避免不必要的长输出
  4. 使用 gpt-4o-mini：简单任务使用更便宜的模型

上下文管理

设置上下文窗口

llm = GPT(
    name="gpt-4o",
    context_window=128000  # 128K tokens
)

上下文压缩

当上下文超出限制时，Chain 会自动触发压缩：

# Chain 自动处理
from tfrobot.brain.chain import SingleChain

chain = SingleChain(llm=llm)
result = chain.run(input_message=user_input)

错误处理

常见错误

错误类型 原因 解决方案
context_length_exceeded 上下文超长 使用 Chain 的 compact 功能
rate_limit_error API 限流 自动重试（已配置）
invalid_api_key API 密钥错误 检查环境变量
insufficient_quota 配额不足 充值或更换模型

手动错误处理

from openai import BadRequestError

try:
    result = llm.complete(current_input=user_input)
except BadRequestError as e:
    if e.code == "context_length_exceeded":
        # 手动压缩
        compacted, _, _, _, _ = llm.collapse_context(
            current_input=user_input,
            conversation=conversation,
            to_size=100000
        )
        result = llm.complete(current_input=user_input, conversation=compacted)

高级用法

流式输出

llm = GPT(name="gpt-4o", stream=True)

result = llm.complete(current_input=user_input)
# result.generations[0].text 会逐步生成

自定义 Base URL

# 使用代理或兼容 API
llm = GPT(
    name="gpt-4o",
    openai_api_base="https://api.openai-proxy.com/v1"
)

Logprobs

llm = GPT(
    name="gpt-4o",
    logprobs=True,
    top_logprobs=5
)

最佳实践

1. Temperature 设置

# 需要创造性（如写作）
llm = GPT(name="gpt-4o", temperature=1.0)

# 需要稳定性（如代码生成）
llm = GPT(name="gpt-4o", temperature=0.0)

2. Prompt 工程

llm.system_msg_prompt = [
    MemoPrompt(template="你是一个专业的 Python 开发者。"),
    ToolPrompt(),
]

llm.after_input_msg_prompt = [
    MemoPrompt(template="请使用 Markdown 格式回复，代码块标明语言。"),
]

3. 工具设计

@tool
def search_code(query: str, language: str = "python") -> str:
    """
    搜索代码示例

    Args:
        query: 搜索关键词
        language: 编程语言（默认 python）
    """
    # 工具实现
    ...

相关文档