用Claude API构建智能助手：从入门到实战，5步打造专属AI应用

huozhe01

197人浏览 · 2026-07-03 18:20:58

huozhe01 · 2026-07-03 18:20:58 发布

用Claude API构建智能助手：从入门到实战，5步打造专属AI应用

引言

你是否想过为自己的网站、应用或者自动化流程添加一个真正懂你的智能助手？OpenAI的GPT系列已经深入人心，但Anthropic推出的Claude系列凭借更强的上下文理解能力、更细致的回答风格以及高达100K token的超长上下文窗口，正成为开发者的新宠。

本文将带你从零开始，利用Claude API（Messages API）构建一个功能完整的智能助手，涵盖核心概念、环境配置、多轮对话、工具调用以及实际部署中的常见陷阱。无论你是希望打造客服机器人、代码审查工具还是个人知识库问答系统，这篇文章都能给你一个扎实的起点。

核心概念：Messages API与Claude模型

在使用Claude API之前，我们需要理解两个关键概念：模型和API接口。

1. Claude可用模型

目前Claude提供多个版本，常用的是：
- Claude 3 Haiku：轻量、快速、成本低，适合简单任务。
- Claude 3 Sonnet：性能与速度均衡，推荐用于大多数助手场景。
- Claude 3 Opus：最智能，但延迟较高、成本更高。

本文示例使用claude-3-sonnet-20240229，性价比高，响应迅速。

2. Messages API格式

Anthropic最新的Messages API采用结构化的消息列表，每一条消息都包含role和content字段：
- role可以是user（用户）或assistant（助手）。
- content支持纯文本或多媒体（图片等），这里我们只关注文本。

一个最简单的请求示例如下：

{
  "model": "claude-3-sonnet-20240229",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "你好，请简单介绍一下你自己。"}
  ]
}

响应中的content数组会包含助手的回答。这种结构天然支持多轮对话——只需将历史消息逐条追加到messages列表中即可。

3. 系统提示(system prompt)

Messages API允许通过system参数设置系统级指令，用于定义助手的角色、语气或行为约束，且该提示不会占用对话历史。这是构建自定义助手风格的核心。

实战：构建一个多轮对话助手

下面我们用Python一步步构建一个命令行智能助手，支持：
- 自定义系统提示（例如：扮演一位技术面试官）
- 多轮对话，记住上下文
- 流式输出（像打字机一样逐词输出）
- 优雅的错误处理

准备工作

你需要拥有Anthropic API的密钥，并将其设为环境变量ANTHROPIC_API_KEY。如果还没有，可以去Anthropic Console申请。

安装官方的Python SDK：

pip install anthropic

完整代码

创建一个文件claude_assistant.py，代码如下：

#!/usr/bin/env python3
"""
基于Claude Messages API的多轮对话助手
支持流式输出、自定义系统提示、历史管理。
"""
import os
import sys
import anthropic

# 从环境变量读取API密钥
API_KEY = os.environ.get("ANTHROPIC_API_KEY")
if not API_KEY:
    sys.exit("请设置环境变量 ANTHROPIC_API_KEY")

# 初始化客户端
client = anthropic.Anthropic(api_key=API_KEY)

# 配置模型与参数
MODEL_NAME = "claude-3-sonnet-20240229"
MAX_TOKENS = 1024
TEMPERATURE = 0.7  # 控制随机性，范围0-1，越高越有创造性

# 系统提示：设定助手角色
SYSTEM_PROMPT = (
    "你是一位资深技术面试官，擅长Java后端领域的面试。"
    "你会根据对话历史逐步深入提问，语气专业但友好。"
    "当候选人回答正确时，给出肯定并追问更难的问题；回答错误时，给予提示。"
)

def chat_loop():
    """主对话循环，维护整个对话历史。"""
    messages = []  # 保存对话历史，每条为{"role": ..., "content": ...}
    print("🤖 智能助手已启动（输入 'exit' 退出，'clear' 清空历史）\n")
    while True:
        try:
            user_input = input("👤 你: ").strip()
        except (KeyboardInterrupt, EOFError):
            print("\n👋 再见！")
            break

        if not user_input:
            continue
        if user_input.lower() == "exit":
            print("👋 再见！")
            break
        if user_input.lower() == "clear":
            messages.clear()
            print("🧹 对话历史已清空。\n")
            continue

        # 添加用户消息到历史
        messages.append({"role": "user", "content": user_input})

        print("🤖 助手: ", end="", flush=True)
        assistant_reply = ""
        try:
            # 使用流式输出调用API
            with client.messages.stream(
                model=MODEL_NAME,
                max_tokens=MAX_TOKENS,
                temperature=TEMPERATURE,
                system=SYSTEM_PROMPT,
                messages=messages,
            ) as stream:
                for text_delta in stream.text_stream:
                    print(text_delta, end="", flush=True)
                    assistant_reply += text_delta
        except anthropic.APIError as e:
            print(f"\n❌ API错误: {e}")
            # 移除刚刚添加的用户消息，避免历史不一致
            if messages and messages[-1]["role"] == "user":
                messages.pop()
            continue
        except Exception as e:
            print(f"\n❌ 未知错误: {e}")
            if messages and messages[-1]["role"] == "user":
                messages.pop()
            continue

        # 打印换行，并将助手回复加入历史
        print("\n")
        messages.append({"role": "assistant", "content": assistant_reply})

if __name__ == "__main__":
    chat_loop()

代码讲解

环境变量与客户端初始化：通过anthropic.Anthropic(api_key=...)创建客户端，自动使用API密钥。
系统提示：system参数作为助手的“灵魂”，在每次请求中都包含但不占用对话历史长度。你可以修改SYSTEM_PROMPT来定制任何角色。
对话历史管理：messages列表以追加的方式保存用户和助手的每一轮消息。这样Claude就能理解整个上下文。
流式输出：使用client.messages.stream()获得Stream对象，然后通过stream.text_stream迭代逐词打印，提升交互体验。
错误处理：捕获anthropic.APIError和通用异常，并从历史中回滚用户消息，避免因API调用失败造成的历史不一致。
特殊命令：clear清空历史，exit退出，扩展性强。

运行与测试

启动后，你可以尝试这样的对话：

👤 你: 你好，请出一道Java多线程的面试题。
🤖 助手: （流式输出题目...）
👤 你: Thread 和 Runnable 有什么区别？
🤖 助手: （给出评价并追问...）

通过改变SYSTEM_PROMPT，你可以瞬间让同一个代码变成英语老师、代码审查员、心理咨询师等等。

进阶：让助手拥有工具（函数调用）

单纯的对话能力有限，我们可能希望助手能查询实时天气、计算数学表达式或调用外部API。Claude支持工具使用（Tool Use） 特性，允许助手输出结构化的函数调用。

工具调用示例：获取当前日期

我们添加一个“获取当前日期”的函数工具，助手在需要时可以请求调用。

需要先定义工具的name、description和input_schema：

tools = [
    {
        "name": "get_current_date",
        "description": "获取当前日期，返回格式为YYYY-MM-DD。",
        "input_schema": {
            "type": "object",
            "properties": {},
            "required": []
        }
    }
]

然后在请求中加入tools参数。当助手判断需要使用工具时，其content中会出现tool_use类型的内容（而非文本），我们需要在客户端模拟执行工具并把结果传回。

简化版实现：

# 伪代码：处理工具调用
response = client.messages.create(
    model=MODEL_NAME,
    max_tokens=MAX_TOKENS,
    system=SYSTEM_PROMPT,
    tools=tools,
    messages=messages,
)

# 检查是否需要调用工具
for block in response.content:
    if block.type == "tool_use":
        # 根据block.name执行本地函数，例如 get_current_date
        if block.name == "get_current_date":
            result = datetime.date.today().isoformat()
        # 将结果作为新的用户消息传回
        messages.append({
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                }
            ]
        })
        # 再次调用模型，获取最终回复
        ...

工具调用让助手真正具备了“执行动作”的能力，可以无缝接入公司内部API、数据库查询等。

常见问题与注意事项

API密钥安全
绝对不要将API密钥硬编码到代码中或上传至公开仓库。使用环境变量或密钥管理服务（如AWS Secrets Manager）。
速率限制与配额
Anthropic对API请求有速率限制（如每分钟请求数），免费试用额度有限。生产环境务必实现重试机制（指数退避），并监控使用量。
Token消耗与成本控制
超长对话会导致messages列表快速增长，消耗大量token。建议：
- 设置max_tokens上限。
- 定期清理过时历史（仅保留最近N轮）。
- 使用Claude Haiku处理简单任务降低成本。
响应内容过滤
Claude内置安全模块，可能会拒绝某些敏感话题。如果业务需要更宽松的审核标准，需通过Anthropic的Trust & Safety流程申请。
流式输出中断处理
网络波动可能导致流中断。代码中已包含基础异常捕获，但生产环境还需考虑断点续传或自动重连。
系统提示的设计技巧
明确、具体、使用正面指令，例如：“你是一个有帮助的助手”不如“你是一个擅长Python的代码审查员，同时输出优点和可改进之处，用友好幽默的语气”。测试不同提示并迭代优化。