跳转到主要内容
本页扩展 原生 Claude 入门,同一个 Python 文件提供纯文本 SSE 和函数工具闭环。两种模式都读取真实 SSE 数据流,完整校验后才打印最终可见答案;不会逐片向终端展示未完成文本。先向管理员确认模型和渠道支持原生流式及函数工具。

准备与运行

使用 Python 3.10+,仅依赖标准库,无需安装供应商 SDK。预先设置网关令牌 API_KEY,然后设置不含 /v1 或 /v1beta 的根地址;允许部署路径前缀。
从文档目录运行;单独保存时,去掉命令中的 examples/。第一条只请求一句问候;第二条提供 multiply,让模型计算 7 × 8,再将结果回传给模型生成最终回答。
API_NATIVE_MODE 默认 text;tools 模式也允许模型直接回答。测试固定了模拟回答,真实模型措辞和是否调用工具均不保证。

事件与闭环

tool_use 结束原因才进入工具执行;end_turn 才接受无工具的最终文本。max_tokens、拒答、缺少完成事件及流内错误都会失败。示例固定 max_tokens: 1024,这是需要模型支持的本地预算,不保证复杂请求不会截断。 thinking_delta 与 signature_delta 分别累加到原 thinking 块,redacted_thinking.data 原样保存。工具回合会重放这些块及原始顺序,但终端只输出 text。示例没有主动启用 thinking;若渠道返回已支持的思考块,也不会丢弃。缺少签名会失败,不自行生成或修改签名。

完整 Python 示例

失败与资源边界

SSE 读取器处理增量 UTF-8、LF / CRLF / CR、注释及多行 data,忽略 id / retry,不会因服务端建议重连就自动重放请求。每次 socket 操作超时 60 秒;这不是整段工作流的总耗时上限。每轮最多 512 个数据事件、4096 行、1,048,576 个解码字符,每行最多 65,536 个字符;这些都是示例边界,不是网关限制。 工具只允许本地纯计算 multiply,参数必须恰好是有限数值 a、b,拒绝布尔值、额外字段和非有限结果。最多 3 次模型请求,每轮最多 4 次工具调用;达到第三轮还要求工具时直接退出。工具结果全部准备好后才发送下一轮。对带副作用的工具,仍需另行实现授权、幂等执行与恢复,不能用这个乘法示例替代事务设计。 HTTP 失败、重定向、错误内容类型、非法 JSON、截断 SSE、异常断连、业务未完成和不支持的协议扩展均返回非零退出状态。不会打印密钥、上游错误体、思考文本或不完整答案;遇到未知事件/内容块采取失败退出策略,需要显式扩展解析器才能支持它们。 Claude 另限制每轮 16 个内容块、每个工具参数字符串 16,384 个字符。服务器内置工具、引用增量及其他未列出的块不在示例支持范围。

验证

运行 npm run check:examples,测试会启动本机 HTTP fixture 并执行这份脚本,检查纯文本与工具模式、完整历史和签名、结果关联、UTF-8 分块、错误与断流、无重试及第二轮失败短路。没有真实模型请求;真实渠道是否返回正确事件和保留签名,仍需部署端验证。 Claude 流式事件 · 工具结果格式 Read in English