Claude Opus 5 API 开发实战：对话、文本生成与结构化输出

做 Claude API 开发时，真正的重点并不是"丢一段提示词进去，再拿一段回答出来"这么简单。到了实际业务里，开发者通常更在意几个更现实的问题：多轮对话怎么做得稳定？文本生成的质量和成本怎么控制？模型返回的内容能不能直接被程序解析和使用？

尤其是在客服系统、内容生产、数据抽取、智能体工作流这些场景里，普通文本往往只是第一步。要让能力真正落地，后面还会涉及 JSON、工具调用、字段校验、异常重试等一整套工程问题。

这篇文章会围绕 Claude Opus 5 API 开发来展开，重点聊三个高频场景：对话、Claude 文本生成，以及 Claude 结构化输出。内容更偏工程实践，可以作为开发初稿或方案设计时的参考。需要说明的是，具体模型名称、能力范围和调用参数，仍然要以 Anthropic 官方控制台或对应云平台的最新文档为准。如果你的环境里暂时还没有 Claude Opus 5，也可以把示例里的模型 ID 换成当前可用的 Claude Opus、Sonnet 或 Haiku 系列模型。

一、Claude API 开发前需要理解的几个概念

Claude API 的主要入口一般是 Messages API。它并不是一个简单的"单轮文本补全接口"，而是通过 messages 数组来组织上下文。用户输入、助手之前的回答、系统指令，甚至工具调用结果，都可以用结构化消息的方式传给模型。

一个最小可用的请求，通常会包含这些参数：

• model：指定要使用的 Claude 模型，比如 Opus、Sonnet、Haiku 系列里的某个具体版本。
• max_tokens：限制模型最多输出多少 token，避免回答过长或失控。
• system：设置全局规则，比如角色、语气、回答边界和禁止事项。
• messages：按顺序传入对话历史。
• temperature：控制输出随机性。数值越低，结果越稳定；数值越高，表达越发散。
• output_config 或工具相关参数：用于结构化输出、工具调用等更高级的能力。

对于内容平台、企业内部系统或者 SaaS 产品来说，做 Claude API 开发时，最好不要把所有希望都压在提示词上。提示词主要负责说明任务目标，API 参数用来控制输出边界，而 JSON Schema 或工具 schema 则负责让结果更容易被程序解析。三者配合起来，效果才会更稳。

二、环境准备：用 Python 调用 Claude API

下面用 Python SDK 举例。实际项目里，API Key 建议放在环境变量中管理，不要直接写进代码，尤其不要提交到代码仓库。

pip install anthropic

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)

如果企业使用国际版云服务代理，或者有统一充值、开票、基础技术支持这类需求，可以结合公司合规和采购流程选择合适的服务渠道。比如 NiceCloud 属于国际版云服务代理，比较适合需要企业充值、优惠折扣、开票和基础技术协助的团队。当然，具体能使用哪些服务、额度是多少、价格和政策如何，还是要以相关平台的最新说明为准。

三、单轮对话：最基础的 Claude 文本生成

最简单的 Claude 文本生成场景，就是单轮请求。比如生成一段产品介绍、总结一篇文章，或者改写一段文案。

message = client.messages.create(
    model="claude-opus-5",  # 示例占位，实际以官方可用模型 ID 为准
    max_tokens=800,
    temperature=0.4,
    system="你是一个严谨的中文技术编辑，回答要准确、简洁、有结构。",
    messages=[
        {
            "role": "user",
            "content": "请用 300 字解释什么是向量数据库，并说明它适合哪些 AI 应用。"
        }
    ]
)

print(message.content[0].text)

在这个例子里，system 负责约束整体风格，user 消息则说明具体要完成的任务。对于内容生成类应用，建议把下面这些信息交代清楚：

第一，内容是写给谁看的，比如开发者、运营人员、管理层，还是普通用户。

第二，输出大概多长，比如 300 字、5 个要点，或者 3 段式结构。

另外，还要说明回答边界。比如能不能合理推测，遇到不确定信息时要不要标注出来。

再有就是输出格式。你希望它返回 Markdown、纯文本、表格，还是 JSON，最好一开始就说清楚。

如果只是写一句"帮我写一篇介绍"，模型通常也能给出一个看起来不错的结果，但可控性会比较差。把场景、受众、长度和格式都说清楚之后，输出质量会稳定很多。

四、多轮对话：不要只把最后一句发给模型

Claude API 本身不会自动记住用户之前说过什么。所谓多轮对话，其实就是开发者把必要的历史消息重新放进 messages 里，再一起传给模型。例如：

messages = [
    {
        "role": "user",
        "content": "我在做一个面向电商客服的 AI 助手。"
    },
    {
        "role": "assistant",
        "content": "可以从商品咨询、订单查询、售后引导和人工转接几个模块设计。"
    },
    {
        "role": "user",
        "content": "请帮我设计其中的售后引导流程。"
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1000,
    temperature=0.3,
    system="你是企业 AI 应用架构顾问，输出要适合产品和研发共同评审。",
    messages=messages
)

print(response.content[0].text)

做多轮对话时，一个很常见的问题是：历史消息越塞越多。这样看起来信息很完整，但实际会带来两个麻烦。一是成本会上升，二是无关历史可能会干扰当前回答。

更稳妥的做法，是只保留最近几轮关键对话；更早的内容可以先做摘要，再作为上下文传入。如果是用户画像、业务规则、商品信息这类长期信息，更适合放在外部数据库或检索系统里，而不是每次都硬塞进对话历史。同时，每轮请求最好记录 usage，观察输入和输出 token 的消耗情况。

在生产系统中，不建议无限追加完整聊天记录。对话记忆本质上应该是一种"可控的上下文管理"，而不是简单地把所有历史原样回放。

五、提升 Claude 文本生成质量的参数与提示词策略

Claude 文本生成的质量，通常由三部分共同决定：模型能力、上下文质量，以及输出约束。模型越强，复杂推理和长文本处理能力一般越好，但这并不代表提示词和参数就可以随便写。

1. temperature：稳定任务建议调低

如果任务是摘要、抽取、分类、客服回复这类比较追求稳定性的场景，temperature 建议设低一些，比如 0 到 0.5 之间。这样输出会更稳定，也更容易复现。

如果是创意标题、广告文案、故事生成，可以适当调高一点，让表达更有变化。不过即便是创意任务，也最好配合明确的质量标准，否则结果容易发散。

2. max_tokens：既控制成本，也控制输出边界

max_tokens 并不是说模型一定会输出这么多，而是给它设置一个最大输出上限。

如果是结构化输出，max_tokens 设得太小，可能导致 JSON 被截断；如果是长文生成，设得过大，又会增加成本和响应时间。实际项目中，可以按任务类型分别设置不同的上限，比如摘要类、分类类、长文类分别使用不同配置。

3. system prompt：写规则，不写愿望

很多低质量的 system prompt 会写成这样："你很专业，请认真回答。"这类话听起来没问题，但对结果的帮助其实有限。

更有效的写法，是给模型明确、可检查的规则，例如：

你是企业级 SaaS 产品文档编辑。
要求：
1. 使用中文；
2. 不编造功能、价格和政策；
3. 对不确定信息使用"需以官方说明为准"；
4. 输出 Markdown；
5. 每个小节必须包含可执行建议。

这种写法更清楚，也更容易验证。对于要上线的系统来说，规则越明确，输出越容易稳定。

六、Claude 结构化输出：为什么比"让模型返回 JSON"更可靠

很多开发者一开始会在提示词里写："请只返回 JSON，不要解释。"在简单任务里，这种办法确实能用。但任务一复杂，就容易出现各种小问题。

比如，JSON 前后夹了几句解释；字段缺失，或者字段名不一致；数组、布尔值、数字类型不符合预期。这些问题对人来说可能一眼能看懂，但对程序来说，就会直接造成解析失败或后续流程异常。

Claude 结构化输出的价值就在这里：通过 JSON Schema 来约束模型响应，让返回结果更适合程序直接解析。比较典型的使用场景包括：

• 从销售线索中提取姓名、邮箱和需求等级；
• 把用户反馈分类为 bug、咨询、投诉或建议；
• 生成固定结构的内容大纲；
• 输出可以入库的商品、订单、文章元数据；
• 给下游工具或自动化工作流提供参数。

换句话说，结构化输出不是为了"看起来像 JSON"，而是为了让程序可以稳定使用。

七、使用 JSON Schema 获取结构化结果

下面这个例子，会让 Claude 从一段用户反馈中提取结构化字段。

import json
from anthropic import Anthropic

client = Anthropic()

schema = {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "description": "反馈类别，例如 bug、功能建议、价格咨询、账号问题"
        },
        "priority": {
            "type": "string",
            "description": "优先级：low、medium、high"
        },
        "summary": {
            "type": "string",
            "description": "一句话概括用户反馈"
        },
        "need_human_followup": {
            "type": "boolean",
            "description": "是否需要人工跟进"
        }
    },
    "required": ["category", "priority", "summary", "need_human_followup"],
    "additionalProperties": False
}

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=500,
    temperature=0,
    messages=[
        {
            "role": "user",
            "content": "用户反馈：我昨晚付款后会员还没到账，客服也没人回复，麻烦尽快处理。"
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": schema
        }
    }
)

data = json.loads(response.content[0].text)
print(data)

可能得到的结果类似这样：

{
  "category": "账号问题",
  "priority": "high",
  "summary": "用户付款后会员未到账且客服未及时回复",
  "need_human_followup": true
}

这里真正重要的，不是模型"会不会写 JSON"，而是输出被 schema 约束之后，程序可以更可靠地执行 json.loads()，然后继续进入数据库、工单系统或自动化流程。对于业务系统来说，这一点非常关键。

八、设计 Claude 结构化输出 Schema 的注意事项

结构化输出并不是 schema 写得越复杂越好。恰恰相反，越接近真实业务需要、越稳定，后期越好维护。实际项目中，可以重点注意下面几个点。

1. 字段越稳定越好

如果某个字段是下游系统必须使用的，就把它放进 required。如果字段可有可无，就要提前想清楚缺失时怎么处理。

不要设计一堆"看起来以后可能有用"的字段。字段越多，模型负担越重，接口维护成本也越高。很多时候，少而准的字段比大而全的结构更实用。

2. 使用 additionalProperties: false

对于对象结构，建议明确设置 additionalProperties: false。这样可以减少模型返回未定义字段的情况，也能降低接口兼容风险。

这在多人协作或多个系统对接时尤其有用，因为字段一旦变多、变乱，后续排查问题会比较麻烦。

3. 枚举值要在描述中写清楚

如果某个字段只能取有限值，可以直接在 schema 里使用 enum，或者至少在 description 里把可选值写清楚。分类、优先级、状态机字段都很适合这样处理。

"priority": {
    "type": "string",
    "enum": ["low", "medium", "high"]
}

这样做的好处很明显：模型输出更统一，后端校验也更简单。

4. 不要把所有校验都交给模型

即便使用了 Claude 结构化输出，服务端也仍然需要做二次校验。比如 JSON 解析、字段类型检查、枚举值校验、空值处理，以及必要时的异常重试。

模型输出更可靠，并不意味着业务系统可以放弃校验。生产系统里，校验这一步不能省。

九、结构化输出与工具调用的区别

Claude API 开发里，还有一个容易混淆的概念：结构化输出和工具调用。

简单来说，JSON 结构化输出适合让模型"直接返回一个结构化结果"；工具调用则更适合让模型"判断应该调用哪个函数，并生成对应参数"。

比如，提取用户反馈类别，用 JSON 输出就很合适。而"根据用户需求查询订单、创建工单、发送通知"这种场景，就更适合工具调用。因为这时候模型不只是给结果，还要协助后端决定下一步动作。

不过需要注意，工具调用时，模型生成的只是工具参数，真正执行动作的仍然应该是你的后端代码。

在安全性要求比较高的系统中，不能让模型直接执行敏感操作。正确做法是：模型负责理解意图、生成参数和建议；后端负责鉴权、校验、审计和执行。这样边界更清楚，也更安全。

十、常见错误与排查建议

1. JSON 被截断

这种情况通常是 max_tokens 设置太小，或者 schema 太复杂。可以适当提高 max_tokens，减少字段数量，或者把一个大任务拆成几个小任务来处理。

2. 输出字段不符合预期

先检查 schema 是否写得足够明确，字段描述有没有含糊不清的地方，是否缺少 required 和 additionalProperties: false。如果是分类任务，建议尽量使用枚举值，减少模型自由发挥的空间。

3. 多轮对话回答跑偏

这通常和上下文有关。可能是传入了太多无关历史，也可能是 system prompt 和用户指令之间存在冲突。可以尝试对历史内容做摘要，把业务规则放在更稳定的位置，并减少噪声上下文。

4. 成本和延迟不可控

建议记录每次请求的输入、输出 token。长文本可以先摘要再处理；简单任务可以使用更轻量的模型；高价值、复杂度更高的任务，再考虑使用 Opus 级模型。这样成本和效果会更平衡。

十一、一个更接近生产的调用流程

在真实业务里，一次 Claude API 调用最好不要只是简单的"请求---返回"。更推荐的流程大概是这样：

先接收用户输入，并做长度、敏感信息和权限检查。然后构造 system prompt、上下文和任务指令。接着根据任务类型，选择普通文本生成、结构化输出，或者工具调用。

调用 Claude API 之后，需要解析返回结果，再做服务端校验。如果校验失败，可以进行有限次数的重试，或者走降级方案。与此同时，还要记录日志、token 使用量和错误信息。最后，再把结果返回前端，或者写入业务系统。

这样设计的好处是，模型负责"理解和生成"，工程系统负责"边界、校验和执行"。分工清楚之后，系统才更容易稳定运行，也更方便后续排查和迭代。

总结

Claude Opus 5 API 开发的关键，不只是调用一个强模型，而是把对话管理、Claude 文本生成和 Claude 结构化输出组合成一套可靠的应用流程。

单轮生成适合内容生产、摘要和改写；多轮对话需要开发者主动管理上下文；结构化输出则解决了 JSON 可解析、字段稳定和下游自动化的问题。

对开发者来说，可以从三个层面优化：用清晰的 system prompt 控制模型行为，用合理的参数控制输出范围，再用 JSON Schema 或工具 schema 控制返回结构。不要只依赖"请严格返回 JSON"这种软约束，也不要把业务校验完全交给模型。

真正可上线的 Claude API 应用，往往不是提示词写得最复杂，而是上下文、结构、校验和异常处理都设计得足够清楚。这样做出来的系统，才更稳，也更接近真实生产环境的要求。