手把手教你配置 API Key 并调用大模型：从环境变量到 OpenAI 兼容接口实战

丨白色风车丨

344人浏览 · 2026-08-07 22:49:17

丨白色风车丨 · 2026-08-07 22:49:17 发布

前言

一、API Key 基础认知：它到底是什么？

二、环境变量配置：为什么必须放后端？

三、实战：用 API Key 发起对话（OpenAI 兼容模式）

四、避坑指南：新手常见问题

总结

前言

在 AI 应用开发中，API Key 是连接你与大模型服务的“钥匙”。但很多新手常犯一个致命错误——把 Key 硬编码在前端或代码里，导致密钥泄露、产生高额费用。本文结合真实项目经验，带你从零掌握 API Key 的安全配置与调用方法，支持 DashScope（通义千问）、DeepSeek、火山引擎等主流平台，代码可直接复用！

一、API Key 基础认知：它到底是什么？

API Key 是平台用于识别用户身份和配额的“访问凭证”。没有它，你的请求会被拒绝；有了它，平台才知道“你是谁”以及“你能用多少资源”。

常见错误码解析：

401/403：Key 缺失或无效（检查是否拼写错误、是否过期）
429：Key 有效但额度不足（需充值或切换模型）

关键提醒：不同平台的 Key 变量名不同，例如：

阿里云 DashScope：DASHSCOPE_API_KEY
DeepSeek：DEEPSEEK_API_KEY
火山引擎：VOLCENGINE_API_KEY

教学建议：开发时可用通用变量名 MODEL_API_KEY，项目中再映射到具体平台，便于切换模型。

二、环境变量配置：为什么必须放后端？

绝对禁止在前端（如 JavaScript、HTML）中直接写 API Key！原因有三：

前端代码可被用户直接查看，Key 极易泄露。
泄露后黑客可盗用你的配额，产生真实费用。
后端可统一做限流、审计、内容过滤，更安全可控。

正确做法：使用 .env 文件存储密钥，通过环境变量读取。

配置步骤：

复制模板文件：

bash

编辑

cp .env.example .env

Windows 用户用 PowerShell：

powershell

编辑

Copy-Item .env.example .env

编辑 .env 文件，填入真实 Key：

env

编辑

DASHSCOPE_API_KEY=sk-你的真实key
DEEPSEEK_API_KEY=sk-你的真实key
VOLCENGINE_API_KEY=你的真实key

Python 读取环境变量：

import os
from dotenv import load_dotenv

load_dotenv()  # 加载 .env 文件
api_key = os.getenv("DASHSCOPE_API_KEY")
if not api_key:
    raise RuntimeError("DASHSCOPE_API_KEY 未配置，请检查 .env 文件")

三、实战：用 API Key 发起对话（OpenAI 兼容模式）

目前主流平台（如 DashScope）均支持 OpenAI 兼容接口，代码可无缝迁移。

方法 1：Python SDK 调用（推荐）

python

编辑

from openai import OpenAI
import os
from dotenv import load_dotenv

load_dotenv()

# 配置客户端（以 DashScope 为例）
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"  # 兼容 OpenAI 的 endpoint
)

# 发起对话
resp = client.chat.completions.create(
    model="qwen-plus",  # 模型名
    messages=[
        {"role": "system", "content": "你是教学助理，请简洁回答。"},
        {"role": "user", "content": "什么是 API Key？"}
    ],
    temperature=0.7
)

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

方法 2：curl 命令调试

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {"role": "user", "content": "请用三点说明 API Key 的作用"}
    ]
  }'

Windows PowerShell 用户：

powershell

编辑

$headers = @{
  "Content-Type" = "application/json"
  "Authorization" = "Bearer $env:DASHSCOPE_API_KEY"
}
$body = @{
  model = "qwen-plus"
  messages = @(@{ role = "user"; content = "解释 API Key 的作用" })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Post -Uri "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions" -Headers $headers -Body $body

四、避坑指南：新手常见问题

Key 泄露风险：永远不要提交 .env 到 Git！在 .gitignore 中添加 .env。
环境变量未加载：确保 load_dotenv() 在读取 os.getenv 之前调用。
Base URL 错误：不同平台的兼容接口地址不同，例如 DashScope 是 https://dashscope.aliyuncs.com/compatible-mode/v1，别写错！
模型名不匹配：qwen-plus 是 DashScope 的模型，DeepSeek 需用 deepseek-chat，注意区分。