HypersHub Logo
能力指南

能力指南

覆盖系统提示词、多轮对话、工具调用、视觉输入、流式响应和生成参数六大核心能力。所有示例均基于 OpenAI 兼容接口，其他格式的参数差异请查阅 API Reference。

系统提示词

system 消息用于设定模型角色、输出风格和行为约束，始终放在 messages 数组的第一位。

Python
completion = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {
            "role": "system",
            "content": (
                "你是一个专业的代码审查助手。"
                "只输出简洁的技术反馈，使用 Markdown 格式，不要解释显而易见的问题。"
            ),
        },
        {
            "role": "user",
            "content": "帮我审查这段代码：\ndef add(a, b):\n    return a + b",
        },
    ],
)

print(completion.choices[0].message.content)
Claude 原生 API 的系统提示词通过顶层 system 字段传递，不放入 messages 数组中。

多轮对话

模型本身无状态。多轮对话需要客户端自行维护历史消息数组，每次请求时将完整历史传入。

messages = [
    {"role": "system", "content": "你是一个耐心的编程教师。"},
    {"role": "user",   "content": "我想学 Python，但完全没有编程经验"},
    {"role": "assistant", "content": "没问题！我们从打印 Hello World 开始..."},
    {"role": "user",   "content": "print 是什么意思？"},
]

completion = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=messages,
)

# 将新回复追加到历史，供下一轮使用
messages.append({
    "role": "assistant",
    "content": completion.choices[0].message.content,
})

工具调用

统一接口使用 OpenAI 的 tools 格式。模型在需要外部数据时返回工具调用，客户端执行后将结果回传，模型再生成最终回复。

Python — 完整工具调用循环
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询城市的实时天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名称，如「上海」"},
            },
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "上海今天天气怎么样？"}]

# Step 1：首次请求，模型决定是否调用工具
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=messages,
    tools=tools,
)

tool_call = resp.choices[0].message.tool_calls[0]
print("模型要调用：", tool_call.function.name)
print("参数：", tool_call.function.arguments)

# Step 2：在本地执行工具（示例直接返回假数据）
tool_result = '{"city": "上海", "temp": "28°C", "desc": "晴"}'

# Step 3：将工具结果追加进 messages，再次请求
messages.append(resp.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": tool_result,
})

final = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=messages,
    tools=tools,
)
print(final.choices[0].message.content)

视觉输入

将文本和图片混合放入 message content 数组。支持 URL 直链和 Base64 两种传入方式。模型需支持多模态能力（如 claude-sonnet-4-6、gpt-5.4、gemini-3.1-pro-preview）。

completion = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图片里有什么？"},
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/photo.jpg"},
            },
        ],
    }],
)
print(completion.choices[0].message.content)
支持格式：JPEG、PNG、GIF、WebP。Base64 方式适合私有图片；公开 URL 无需转码，更简洁。

流式响应

设置 stream: true，响应以 SSE（Server-Sent Events）形式逐块返回，适合聊天 UI 和长文本生成。

stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "用 200 字介绍量子计算"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

生成参数

通过调整生成参数，可以控制输出的随机性、长度和截止条件。以下是常用参数说明。

参数类型说明
temperaturefloat 0–2控制随机性。0 最确定，2 最有创意。通常设 0.7–1.0。
max_tokensinteger最大输出 token 数。超出后截断。不填则使用模型默认上限。
top_pfloat 0–1核采样。与 temperature 二选一调整，不建议同时修改两者。
stopstring | array停止词。遇到指定字符串后立即停止生成。
ninteger一次生成 n 条候选，默认 1。多候选会按倍数计费。
seedinteger随机种子。相同 seed + 相同输入可提升结果可复现性。
Python — 调整生成参数
completion = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "写一首关于秋天的短诗"}],
    temperature=0.9,     # 稍高的随机性，适合创意写作
    max_tokens=256,      # 限制输出长度
    stop=["\n\n\n"],    # 遇到三个连续换行时停止
)