登录
文档导航
开发集成

Python / Node.js SDK

使用 Python、Node.js 和环境变量接入业务服务。

本页目录
  1. 第一步：创建服务专用 Key
  2. 第二步：准备环境变量
  3. 第三步：完成基础连通性测试
  4. Python OpenAI SDK
  5. Node.js OpenAI SDK
  6. 使用 Responses API
  7. 使用 Anthropic SDK
  8. 上线前增加的保护
  9. 部署时如何提供 Secret
  10. 上线验收清单

自研后端、Agent Server 和自动化脚本可以直接使用 OpenAI 或 Anthropic SDK。正确的生产接入顺序是：创建服务专用 Key -> 查询模型 -> 在本地跑最小示例 -> 增加超时和错误处理 -> 使用 Secret 部署。

第一步：创建服务专用 Key

  1. 登录 https://console.zcloudapi.com。
  2. 在「API 密钥」创建一条新 Key。
  3. 名称写明服务和环境，例如 order-agent-dev 或 report-api-prod。
  4. 只开放该服务真正需要的模型。
  5. 给生产 Key 设置可承受的额度上限。
  6. 开发、测试和生产分别使用不同 Key。

第二步：准备环境变量

下面的 YOUR_TEXT_MODEL_ID 是占位符，执行 SDK 示例前必须替换为本人 Key 的 /v1/models 返回结果中支持 Chat Completions 的完整文本模型 ID。

macOS / Linux：

export ZHICLOUD_BASE_URL="https://api.zcloudapi.com/v1"
export ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
export ZHICLOUD_MODEL="YOUR_TEXT_MODEL_ID"

Windows PowerShell：

$env:ZHICLOUD_BASE_URL="https://api.zcloudapi.com/v1"
$env:ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
$env:ZHICLOUD_MODEL="YOUR_TEXT_MODEL_ID"

先查询 /v1/models 并替换 ZHICLOUD_MODEL。模型可见不代表支持所有协议和参数；使用 Responses 或 Anthropic 示例时，需另外选择支持对应协议的模型，并以真实请求和使用日志验证。

第三步：完成基础连通性测试

curl "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

再执行一次最小 Chat Completions 请求。基础 curl 没有成功前，不要开始排查 SDK。

Python OpenAI SDK

1. 创建独立项目环境

mkdir zhicloud-python-service
cd zhicloud-python-service
python -m venv .venv

激活环境。

macOS / Linux：

source .venv/bin/activate

Windows PowerShell：

.venv\Scripts\Activate.ps1

2. 安装依赖

python -m pip install --upgrade openai

3. 新建 app.py

import os
import sys

from openai import APIConnectionError, APIStatusError, OpenAI, RateLimitError

required = ["ZHICLOUD_API_KEY", "ZHICLOUD_BASE_URL", "ZHICLOUD_MODEL"]
missing = [name for name in required if not os.environ.get(name)]
if missing:
    raise RuntimeError(f"缺少环境变量: {', '.join(missing)}")

client = OpenAI(
    api_key=os.environ["ZHICLOUD_API_KEY"],
    base_url=os.environ["ZHICLOUD_BASE_URL"],
    timeout=60.0,
    max_retries=2,
)

try:
    response = client.chat.completions.create(
        model=os.environ["ZHICLOUD_MODEL"],
        messages=[{"role": "user", "content": "只回复 OK"}],
        max_tokens=32,
    )
except RateLimitError:
    print("请求受到限流，请降低并发后重试", file=sys.stderr)
    raise
except APIConnectionError:
    print("无法连接模型 API，请检查网络和 Base URL", file=sys.stderr)
    raise
except APIStatusError as error:
    print(f"API 返回状态码 {error.status_code}", file=sys.stderr)
    raise

print(response.choices[0].message.content)
print(response.usage)

4. 运行并验证

python app.py

确认输出 OK 和用量，然后到控制台使用日志核对同一次请求。

Node.js OpenAI SDK

1. 创建项目并安装依赖

mkdir zhicloud-node-service
cd zhicloud-node-service
npm init -y
npm install openai

2. 新建 app.mjs

import OpenAI from 'openai'

const required = ['ZHICLOUD_API_KEY', 'ZHICLOUD_BASE_URL', 'ZHICLOUD_MODEL']
const missing = required.filter((name) => !process.env[name])
if (missing.length > 0) {
  throw new Error(`缺少环境变量: ${missing.join(', ')}`)
}

const client = new OpenAI({
  apiKey: process.env.ZHICLOUD_API_KEY,
  baseURL: process.env.ZHICLOUD_BASE_URL,
  timeout: 60_000,
  maxRetries: 2,
})

try {
  const response = await client.chat.completions.create({
    model: process.env.ZHICLOUD_MODEL,
    messages: [{ role: 'user', content: '只回复 OK' }],
    max_tokens: 32,
  })

  console.log(response.choices[0].message.content)
  console.log(response.usage)
} catch (error) {
  console.error('ZCloudAPI 请求失败', {
    name: error?.name,
    status: error?.status,
    message: error?.message,
  })
  process.exitCode = 1
}

3. 运行并验证

node app.mjs

不要在错误日志中输出 SDK 客户端对象、完整 Header 或环境变量。

使用 Responses API

Codex 或 Agent 服务使用 Responses API 时，只改变 SDK 方法和输入结构：

response = client.responses.create(
    model=os.environ["ZHICLOUD_MODEL"],
    input="只回复 OK",
    max_output_tokens=32,
)

print(response.output_text)

完整返回结构和工具调用注意事项见「Responses API」。

使用 Anthropic SDK

Claude 服务应使用 Anthropic SDK。先在上文的独立 Python 环境安装依赖：

python -m pip install --upgrade anthropic

把 base_url 设为不带 /v1 的 API Origin；SDK 会自行追加 /v1/messages。首次连通性测试关闭自动重试，便于核对单次请求：

import os

from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ZHICLOUD_API_KEY"],
    base_url=os.environ.get("ZHICLOUD_ANTHROPIC_BASE_URL", "https://api.zcloudapi.com"),
    timeout=60.0,
    max_retries=0,
)

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=32,
    messages=[{"role": "user", "content": "只回复 OK"}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

最近验证：2026 年 10 月 16 日，Python 3.10.12、Anthropic SDK 1.15.0，以上 Messages 最小调用返回 OK、end_turn 和有效 usage，并与站内使用日志一致。模型权限和可用性仍以当前 Key 的实际配置为准。

上线前增加的保护

超时

  • 普通文本建议从 60 秒开始。
  • 推理、Agent 和图片请求需要更长超时。
  • 同时设置连接超时和整体请求超时，避免无限等待。

重试

  • 只对网络错误、429 和部分 5xx 做有限重试。
  • 使用指数退避并增加随机抖动。
  • 不要对所有 400、401、403 自动重试。
  • 有副作用的工具调用需要业务幂等键，避免重试导致重复执行。

日志

建议记录：

  • 业务 request ID。
  • 模型名、接口、状态码和耗时。
  • 输入与输出 Token 数量。
  • 是否重试以及最终结果。

不要记录：

  • 完整 API Key 和 Authorization Header。
  • 密码、私钥和上游凭据。
  • 没有业务必要的完整敏感请求正文。

模型可用性

  1. 部署前用生产 Key 查询 /v1/models。
  2. 启动时检查目标模型是否存在。
  3. 为关键业务准备经过测试的备用模型。
  4. 切换模型时重新验证协议、参数和价格。

部署时如何提供 Secret

环境 推荐方式
GitHub Actions Repository / Environment Secrets
Docker Compose 服务器 .env 或 Docker Secret
Kubernetes Kubernetes Secret 或外部密钥管理服务
云函数 平台 Secret / Environment Variables
本地开发 密码管理器或未提交的本地环境文件

把 .env 加入 .gitignore 只能降低误提交风险，不能替代正式 Secret 管理。

上线验收清单

  • 生产 Key 只开放必要模型和额度。
  • /v1/models 返回目标模型。
  • 最小 SDK 请求返回 200 和正文。
  • SDK 能读取 usage。
  • 控制台使用日志有对应记录。
  • 超时、有限重试和错误分类已经配置。
  • 日志不会输出完整 Key 和敏感正文。
  • Key 只存在于部署环境的 Secret 中。
  • 轮换 Key 时可以在不中断服务的情况下切换。