DeepSeek API 使用教程：国产大模型从注册到调用（Python 实战）

python3 --version

mkdir deepseek-quickstart && cd deepseek-quickstart
python3 -m venv .venv && source .venv/bin/activate
pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get('DEEPSEEK_API_KEY'),
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Hello"},
    ],
    stream=False,
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}}
)

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

export DEEPSEEK_API_KEY="你的key"
python hello_deepseek.py

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get('DEEPSEEK_API_KEY'),
    base_url="https://api.deepseek.com"
)

messages = [
    {"role": "system", "content": "你是耐心的中文客服。先道歉，再解决问题。"},
    {"role": "user", "content": "我的会员没生效！"},
    {"role": "assistant", "content": "非常抱歉！我来帮您查一下，请问是通过哪个渠道充值的？"},
    {"role": "user", "content": "微信，卡了十分钟了"},
]

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    stream=False,
)

print(resp.choices[0].message.content)

from openai import OpenAI

client = OpenAI(
    base_url="https://cloudzone-api.cyou/v1",   # 中转站 OpenAI 兼容端点，以控制台显示为准
    api_key="你的中转站Key",
)

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

#!/usr/bin/env bash
set -u
# ============================================================
#  DeepSeek API 使用教程 一键脚本（macOS / Linux / WSL）
#  公开源码，欢迎审查 —— 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
# ============================================================

GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; CYAN='\033[0;36m'; NC='\033[0m'
info()  { echo -e "${GREEN}[INFO]${NC} $1"; }
warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }
step()  { echo -e "${CYAN}[STEP]${NC} $1"; }

CLOUDZONE_URL="https://cloudzone-api.cyou"
CLOUDZONE_API_BASE="https://cloudzone-api.cyou/v1"
DEEPSEEK_OFFICIAL_BASE="https://api.deepseek.com"

detect_network() {
  step "检测网络环境（国内 / 国外）..."
  if curl -fsI --max-time 5 "https://claude.ai" >/dev/null 2>&1; then
    info "可直连 claude.ai，判定为海外网络"
    echo "overseas"
  else
    warn "无法直连 claude.ai，判定为国内网络环境（将自动切换国内镜像）"
    echo "domestic"
  fi
}

check_python() {
  step "检查 Python 3..."
  if command -v python3 >/dev/null 2>&1 && python3 --version >/dev/null 2>&1; then
    PY="python3"
    info "找到 python3：$(python3 --version 2>&1)"
    return 0
  fi
  error "未找到 python3。请先安装：https://www.python.org/downloads/ （Windows 建议使用 WSL 后执行本脚本）"
  return 1
}

setup_env() {
  local net="$1"
  step "创建虚拟环境并安装 openai SDK（约 1-2 分钟）..."
  mkdir -p deepseek-quickstart && cd deepseek-quickstart || return 1
  python3 -m venv .venv 2>/dev/null || { error "创建虚拟环境失败，手动执行：python3 -m venv .venv"; return 1; }
  # shellcheck disable=SC1091
  source .venv/bin/activate || { warn "激活虚拟环境失败，继续使用系统环境"; }

  step "安装 openai SDK（DeepSeek 官方兼容包）..."
  local pypi="https://pypi.org/simple"
  if [ "$net" = "domestic" ]; then
    pypi="https://pypi.tuna.tsinghua.edu.cn/simple"
  fi

  if pip install openai -i "$pypi" --timeout 60 >/dev/null 2>&1; then
    info "SDK 安装成功"
    return 0
  fi
  warn "主源失败，回退备用镜像（阿里云 PyPI）..."
  if pip install openai -i "https://mirrors.aliyun.com/pypi/simple" --timeout 60 >/dev/null 2>&1; then
    info "备用镜像安装成功"
    return 0
  fi
  error "SDK 安装失败。请手动执行：pip install openai -i https://pypi.tuna.tsinghua.edu.cn/simple"
  return 1
}

configure_api() {
  step "配置 API Key..."
  echo ""
  echo "调用 DeepSeek 需要 API Key。两个选择："
  echo "  官方渠道：platform.deepseek.com 注册，国内直连、支付宝充值"
  echo "  云间 API 中转站：一把 Key 同时调 DeepSeek / Claude / GPT / GLM 等 90+ 模型，DeepSeek V4 低至官方 0.3 倍"
  echo ""
  echo "是否跳转云间 API 注册并获取 Key？"
  echo "  Y - 立即跳转至 ${CLOUDZONE_URL}"
  echo "  N - 使用我自己的 Key（官方或第三方）"
  read -r -p "请选择 [Y/N]: " choice

  local API_KEY=""
  local BASE_URL="$CLOUDZONE_API_BASE"
  if [ "${choice:-N}" = "Y" ] || [ "${choice:-N}" = "y" ]; then
    info "正在打开浏览器..."
    if command -v xdg-open >/dev/null 2>&1; then
      xdg-open "$CLOUDZONE_URL" >/dev/null 2>&1
    elif command -v open >/dev/null 2>&1; then
      open "$CLOUDZONE_URL" >/dev/null 2>&1
    else
      warn "无法自动打开浏览器，请手动访问：$CLOUDZONE_URL"
    fi
    echo "注册后在控制台复制 Key（以 sk- 开头）。"
    read -r -p "粘贴你的 API Key: " API_KEY
    read -r -p "中转地址(直接回车用默认 ${CLOUDZONE_API_BASE}): " input_base
    [ -n "${input_base:-}" ] && BASE_URL="$input_base"
  else
    read -r -s -p "请输入你的 API Key (sk-...): " API_KEY
    echo
    echo "官方 Key 请用默认地址 https://api.deepseek.com；中转站 Key 请填其中转地址。"
    read -r -p "API 地址(直接回车用默认 ${DEEPSEEK_OFFICIAL_BASE}): " input_base
    BASE_URL="${input_base:-$DEEPSEEK_OFFICIAL_BASE}"
  fi

  if [ -z "${API_KEY:-}" ]; then
    error "未输入 API Key，跳过配置。可稍后手动设置环境变量后重跑。"
    return 1
  fi

  local SHELL_RC=""
  case "$SHELL" in
    */zsh)  SHELL_RC="$HOME/.zshrc" ;;
    */bash) SHELL_RC="$HOME/.bashrc" ;;
    *)      SHELL_RC="$HOME/.profile" ;;
  esac

  info "写入环境变量到 $SHELL_RC（仅 DEEPSEEK_API_KEY 与 DEEPSEEK_BASE_URL 两个变量，原值备份 .bak）"
  if [ -f "$SHELL_RC" ]; then
    sed -i.bak '/DEEPSEEK_API_KEY/d; /DEEPSEEK_BASE_URL/d' "$SHELL_RC"
  fi
  {
    echo ""
    echo "# DeepSeek API - 由一键脚本写入"
    echo "export DEEPSEEK_API_KEY=\"$API_KEY\""
    echo "export DEEPSEEK_BASE_URL=\"$BASE_URL\""
  } >> "$SHELL_RC"

  export DEEPSEEK_API_KEY="$API_KEY"
  export DEEPSEEK_BASE_URL="$BASE_URL"

  info "配置完成！"
  echo "  API Key : ${API_KEY:0:10}********"
  echo "  Base URL: $BASE_URL"
  echo ""
  warn "新开终端窗口后永久生效，或立即执行：source $SHELL_RC"
}

write_demo() {
  step "生成示例代码 hello_deepseek.py ..."
  cat > hello_deepseek.py <<'PYEOF'
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get('DEEPSEEK_API_KEY'),
    base_url=os.environ.get('DEEPSEEK_BASE_URL', 'https://api.deepseek.com'),
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
    stream=False,
)

print(response.choices[0].message.content)
PYEOF
  info "已生成 deepseek-quickstart/hello_deepseek.py"
}

main() {
  echo "============================================"
  echo "  DeepSeek API 使用教程 一键脚本"
  echo "  适用于 macOS / Linux / WSL"
  echo "  默认接入：云间 API 中转站"
  echo "============================================"
  echo ""

  local NET
  NET=$(detect_network)

  if ! check_python; then
    error "缺少 Python 3，脚本终止。请先安装 Python 后重跑。"
    exit 1
  fi

  if ! setup_env "$NET"; then
    error "环境准备失败，脚本终止。请按上方提示手动处理。"
    exit 1
  fi

  configure_api || warn "Key 未配置，示例代码仍会生成，运行时需要先 export DEEPSEEK_API_KEY"

  write_demo

  echo ""
  echo "============================================"
  info "全部完成！"
  echo "  运行示例：cd deepseek-quickstart && source .venv/bin/activate && python hello_deepseek.py"
  echo "============================================"
}

main "$@"

# ============================================================
#  DeepSeek API 使用教程 一键脚本（Windows PowerShell）
#  公开源码，欢迎审查 -- 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
# ============================================================
$ErrorActionPreference = "Stop"

function Write-Info  { Write-Host "[INFO] $args" -ForegroundColor Green }
function Write-Warn  { Write-Host "[WARN] $args" -ForegroundColor Yellow }
function Write-Err   { Write-Host "[ERROR] $args" -ForegroundColor Red }
function Write-Step  { Write-Host "[STEP] $args" -ForegroundColor Cyan }

$CLOUDZONE_URL = "https://cloudzone-api.cyou"
$CLOUDZONE_API_BASE = "https://cloudzone-api.cyou/v1"
$DEEPSEEK_OFFICIAL_BASE = "https://api.deepseek.com"

function Detect-Network {
    Write-Step "检测网络环境（国内 / 国外）..."
    try {
        $null = Invoke-WebRequest -Uri "https://claude.ai" -Method Head -TimeoutSec 5 -UseBasicParsing
        Write-Info "可直连 claude.ai，判定为海外网络"
        return "overseas"
    } catch {
        Write-Warn "无法直连 claude.ai，判定为国内网络环境（将自动切换国内镜像）"
        return "domestic"
    }
}

function Find-Python {
    Write-Step "检查 Python 3..."
    $python = $null
    foreach ($candidate in @("python", "py")) {
        try {
            $out = & $candidate --version 2>&1
            if ($LASTEXITCODE -eq 0) { $python = $candidate; break }
        } catch { }
    }
    if ($null -eq $python) {
        Write-Err "未找到 Python。请先安装：https://www.python.org/downloads/ （安装时勾选 Add Python to PATH）"
        return $null
    }
    Write-Info "找到 Python：$(& $python --version 2>&1)"
    return $python
}

function Setup-Env {
    param([string]$Net)
    Write-Step "创建虚拟环境并安装 openai SDK（约 1-2 分钟）..."
    New-Item -ItemType Directory -Force -Path "deepseek-quickstart" | Out-Null
    Set-Location "deepseek-quickstart"

    & $script:PY -m venv .venv
    if ($LASTEXITCODE -ne 0) {
        Write-Err "创建虚拟环境失败，手动执行：$script:PY -m venv .venv"
        return $false
    }
    $script:PY = Join-Path (Get-Location) ".venv\Scripts\python.exe"

    Write-Step "安装 openai SDK（DeepSeek 官方兼容包）..."
    $pypi = if ($Net -eq "domestic") { "https://pypi.tuna.tsinghua.edu.cn/simple" } else { "https://pypi.org/simple" }

    & $script:PY -m pip install openai -i $pypi --timeout 60 2>$null
    if ($LASTEXITCODE -eq 0) {
        Write-Info "SDK 安装成功"
        return $true
    }
    Write-Warn "主源失败，回退备用镜像（阿里云 PyPI）..."
    & $script:PY -m pip install openai -i "https://mirrors.aliyun.com/pypi/simple" --timeout 60 2>$null
    if ($LASTEXITCODE -eq 0) {
        Write-Info "备用镜像安装成功"
        return $true
    }
    Write-Err "SDK 安装失败。请手动执行：$script:PY -m pip install openai -i https://pypi.tuna.tsinghua.edu.cn/simple"
    return $false
}

function Configure-Api {
    Write-Step "配置 API Key..."
    Write-Host ""
    Write-Host "调用 DeepSeek 需要 API Key。两个选择："
    Write-Host "  官方渠道：platform.deepseek.com 注册，国内直连、支付宝充值"
    Write-Host "  云间 API 中转站：一把 Key 同时调 DeepSeek / Claude / GPT / GLM 等 90+ 模型，DeepSeek V4 低至官方 0.3 倍"
    Write-Host ""
    Write-Host "是否跳转云间 API 注册并获取 Key？"
    Write-Host "  Y - 立即跳转至 $CLOUDZONE_URL"
    Write-Host "  N - 使用我自己的 Key（官方或第三方）"
    $choice = Read-Host "请选择 [Y/N]"

    $apiKey = ""
    $baseUrl = $CLOUDZONE_API_BASE
    if ($choice -eq "Y" -or $choice -eq "y") {
        Write-Info "正在打开浏览器..."
        try {
            Start-Process "$CLOUDZONE_URL"
        } catch {
            Write-Warn "无法自动打开浏览器，请手动访问：$CLOUDZONE_URL"
        }
        Write-Host "注册后在控制台复制 Key（以 sk- 开头）。"
    } else {
        $baseUrl = $DEEPSEEK_OFFICIAL_BASE
        Write-Host "官方 Key 请用默认地址 https://api.deepseek.com；中转站 Key 请填其中转地址。"
    }

    $sec = Read-Host "粘贴你的 API Key（输入时不显示字符）" -AsSecureString
    $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)
    $apiKey = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
    [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)

    if ([string]::IsNullOrWhiteSpace($apiKey)) {
        Write-Err "未输入 API Key，跳过配置。可稍后手动设置环境变量后重跑。"
        return $false
    }

    $inputBase = Read-Host "API 地址(直接回车用默认 ${baseUrl})"
    if (-not [string]::IsNullOrWhiteSpace($inputBase)) { $baseUrl = $inputBase }

    # 写入用户级环境变量（永久），并导出到当前会话。原因：示例代码从环境变量自动读取 Key。
    [Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", $apiKey, "User")
    [Environment]::SetEnvironmentVariable("DEEPSEEK_BASE_URL", $baseUrl, "User")
    $env:DEEPSEEK_API_KEY = $apiKey
    $env:DEEPSEEK_BASE_URL = $baseUrl

    Write-Info "配置完成！"
    Write-Host "  API Key : $($apiKey.Substring(0, [Math]::Min(10, $apiKey.Length)))********"
    Write-Host "  Base URL: $baseUrl"
    Write-Host ""
    Write-Warn "新开终端窗口后永久生效（当前会话已立即生效）"
    return $true
}

function Write-Demo {
    Write-Step "生成示例代码 hello_deepseek.py ..."
    @'
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get('DEEPSEEK_API_KEY'),
    base_url=os.environ.get('DEEPSEEK_BASE_URL', 'https://api.deepseek.com'),
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
    stream=False,
)

print(response.choices[0].message.content)
'@ | Set-Content -Path "hello_deepseek.py" -Encoding UTF8
    Write-Info "已生成 deepseek-quickstart/hello_deepseek.py"
}

Write-Host "============================================"
Write-Host "  DeepSeek API 使用教程 一键脚本"
Write-Host "  适用于 Windows（PowerShell）"
Write-Host "  默认接入：云间 API 中转站"
Write-Host "============================================"
Write-Host ""

$net = Detect-Network

$script:PY = Find-Python
if ($null -eq $script:PY) {
    Write-Err "缺少 Python，脚本终止。请先安装 Python 后重跑。"
    exit 1
}

if (-not (Setup-Env -Net $net)) {
    Write-Err "环境准备失败，脚本终止。请按上方提示手动处理。"
    exit 1
}

if (-not (Configure-Api)) {
    Write-Warn "Key 未配置，示例代码仍会生成，运行时需要先设置 DEEPSEEK_API_KEY"
}

Write-Demo

Write-Host ""
Write-Host "============================================"
Write-Info "全部完成！"
Write-Host "  运行示例：cd deepseek-quickstart; .\.venv\Scripts\python hello_deepseek.py"
Write-Host "============================================"