Python SDK 实战项目

理论学够了，现在来一个完整项目。我们将用 Python + Claude SDK 构建一个「智能文档问答助手」——用户上传文档，AI 回答问题并引用原文。这个项目综合运用了多轮对话、工具调用、结构化输出等你之前学到的技能。

你将学到什么

• 从零搭建一个完整的 Claude Python 项目
• 项目结构和依赖管理
• 实现文档问答的核心功能
• 对话历史管理和成本优化

项目概述

功能：

• 用户加载本地文档（TXT/Markdown）
• 提出问题，Claude 基于文档内容回答
• 回答附带引用标记
• 支持多轮追问
• 显示每次的 token 用量和费用

项目结构

doc-qa-assistant/
  main.py          # 入口
  assistant.py     # 核心逻辑
  requirements.txt
  .env             # API Key

requirements.txt

anthropic>=0.40.0
python-dotenv>=1.0.0

assistant.py — 核心代码

import anthropic
from pathlib import Path

class DocQAAssistant:
    def __init__(self):
        self.client = anthropic.Anthropic()
        self.messages = []
        self.documents = []
        self.total_input_tokens = 0
        self.total_output_tokens = 0

    def load_document(self, path: str):
        text = Path(path).read_text(encoding="utf-8")
        self.documents.append({
            "title": Path(path).name,
            "content": text
        })
        print(f"已加载: {Path(path).name} ({len(text)} 字)")

    def ask(self, question: str) -> str:
        # 构建消息内容
        content = []
        for doc in self.documents:
            content.append({
                "type": "document",
                "source": {
                    "type": "text",
                    "media_type": "text/plain",
                    "data": doc["content"],
                },
                "title": doc["title"],
                "citations": {"enabled": True},
            })
        content.append({"type": "text", "text": question})

        self.messages.append({"role": "user", "content": content})

        response = self.client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=2048,
            system="你是文档问答助手。基于提供的文档回答问题，引用原文。如果文档中没有相关信息，坦诚告知。",
            messages=self.messages,
        )

        # 更新统计
        self.total_input_tokens += response.usage.input_tokens
        self.total_output_tokens += response.usage.output_tokens

        # 提取回答文本
        answer_parts = []
        for block in response.content:
            if hasattr(block, "text"):
                answer_parts.append(block.text)

        answer = "".join(answer_parts)
        self.messages.append({"role": "assistant", "content": response.content})

        return answer

    def get_cost(self) -> float:
        return (
            self.total_input_tokens * 3 / 1_000_000 +
            self.total_output_tokens * 15 / 1_000_000
        )

main.py — 入口

from dotenv import load_dotenv
from assistant import DocQAAssistant

load_dotenv()

def main():
    assistant = DocQAAssistant()

    # 加载文档
    print("请输入文档路径（输入空行结束）：")
    while True:
        path = input("> ").strip()
        if not path:
            break
        assistant.load_document(path)

    if not assistant.documents:
        print("未加载任何文档，退出。")
        return

    # 对话循环
    print("\n文档已就绪。开始提问（输入 quit 退出）：\n")
    while True:
        question = input("你: ").strip()
        if question.lower() == "quit":
            break

        answer = assistant.ask(question)
        print(f"\nAssistant: {answer}")
        print(f"  [累计费用: ${assistant.get_cost():.4f}]\n")

    print(f"\n总费用: ${assistant.get_cost():.4f}")

if __name__ == "__main__":
    main()

运行

# 安装依赖
pip install -r requirements.txt

# 设置 API Key
echo "ANTHROPIC_API_KEY=sk-ant-your-key" > .env

# 运行
python main.py

扩展方向

• 添加 PDF 支持：用 PyPDF2 提取 PDF 文本
• 向量检索：文档太长时先做向量搜索，只传相关段落
• Web 界面：用 Streamlit 或 Gradio 添加 UI
• 缓存优化：文档内容用 Prompt Caching 缓存

实战练习

Tip: 把这个项目跑起来。

1. 复制上面的代码，创建项目并运行
2. 加载一份你的文档，测试问答效果
3. 添加一个新功能：让 Claude 生成文档的摘要

关键要点

Note: 本文核心总结

• 完整项目包含：文档加载、多轮问答、引用标注、成本追踪
• 核心是 messages 数组的管理和 Citations 的使用
• 实际项目中要加入向量检索处理长文档
• 监控 token 消耗是必须的

延伸阅读

• 下一篇：TypeScript SDK 实战项目