AI API 术语表大全：开发者在集成前必须掌握的 50+ 核心概念

我曾经因为把 stream=True 和 stream=False 搞混，导致整个实时翻译管道崩溃了 3 次。那天晚上我对着 ConnectionError: timeout after 30s 错误日志发呆，直到凌晨 2 点才意识到——我根本不理解这些 API 参数的实际含义。

如果你也曾在集成 OpenAI / Claude / Gemini API 时被各种术语绕晕，这篇术语表就是为你而写。所有示例均使用 HolySheep AI 作为演示平台，定价低至 $0.42/MTok，延迟低于 50ms，支持微信/支付宝充值。

一、请求与响应核心参数

1. base_url 与 endpoint

base_url 是 API 服务器的基础地址，所有请求都会追加到该地址后面。HolySheep 的 base_url 固定为：

# ✅ 正确的 HolySheep 配置
base_url = "https://api.holysheep.ai/v1"

❌ 常见错误：混淆了 base_url 和完整 URL
错误示例（不要这样做！）
base_url = "https://api.holysheep.ai/v1/chat/completions"  # 这会导致 404

当你调用 /chat/completions 接口时，实际请求 URL = base_url + endpoint。

2. model 参数

指定要使用的 AI 模型，不同模型的定价和能力差异巨大：

• GPT-4.1 — $8/MTok，推理能力强，适合复杂任务
• Claude Sonnet 4.5 — $15/MTok，擅长长文本分析
• Gemini 2.5 Flash — $2.50/MTok，性价比首选
• DeepSeek V3.2 — $0.42/MTok，成本最低的强力模型

import requests

response = requests.post(
    "https://api.holysheep.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "deepseek-v3.2",      # 指定模型
        "messages": [{"role": "user", "content": "你好"}],
        "max_tokens": 1000
    }
)
print(response.json())

3. messages 与 role 系统

对话内容通过 messages 数组传递，每个消息包含三个字段：

• role — 角色：system（系统）、user（用户）、assistant（助手）
• content — 消息内容
• name（可选）— 对话参与者名称

# 标准的 messages 结构
messages = [
    {
        "role": "system",
        "content": "你是一个专业的代码审查员"
    },
    {
        "role": "user",
        "content": "帮我审查这段 Python 代码"
    },
    {
        "role": "assistant",
        "content": "好的，请提供代码"
    },
    {
        "role": "user",
        "content": "def add(a, b): return a + b"
    }
]

4. temperature 与 top_p（采样控制）

这两个参数控制输出的「随机性」：

• temperature — 值越高输出越随机（0.0-2.0），默认 1.0
• top_p — 核采样阈值，越低输出越集中（0.0-1.0）

重要规则：同时设置两者时，API 会自动忽略 temperature，只用 top_p。

# 创意写作：需要高随机性
payload = {
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "写一个科幻故事开头"}],
    "temperature": 1.2,    # 高随机性
    "top_p": 0.95
}

精确回答：需要确定性
payload = {
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "1+1等于几"}],
    "temperature": 0.0     # 完全确定性输出
}

5. max_tokens 与 stop 序列

• max_tokens — 限制单次响应的最大 token 数，防止过量消耗
• stop — 遇到指定字符串时停止生成（最多 4 个序列）

# 限制输出长度并指定停止词
response = requests.post(
    "https://api.holysheep.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY"},
    json={
        "model": "gemini-2.5-flash",
        "messages": [{"role": "user", "content": "解释量子计算"}],
        "max_tokens": 500,       # 最多生成 500 tokens
        "stop": ["。", "?"]     # 遇到句号或问号停止
    }
)

6. stream 流式输出

stream=True 开启 SSE（Server-Sent Events）逐块返回，适合实时显示打字效果。stream=False 等待完整响应后一次性返回。

# 流式输出示例（stream=True）
import json
import sseclient

response = requests.post(
    "https://api.holysheep.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY"},
    json={
        "model": "claude-sonnet-4.5",
        "messages": [{"role": "user", "content": "用一句话介绍自己"}],
        "stream": True
    },
    stream=True
)

client = sseclient.SSEClient(response)
for event in client.events():
    if event.data:
        data = json.loads(event.data)
        if "choices" in data:
            delta = data["choices"][0].get("delta", {})
            if "content" in delta:
                print(delta["content"], end="", flush=True)

二、Token 计费核心概念

7. Token 是什么？

Token 是 AI 处理文本的最小单位。英文约 1 token = 4 个字符，1 个中文汉字约 1-2 tokens。API 按输入 + 输出的总 token 数计费。

• 输入 tokens = system prompt + 全部 history messages
• 输出 tokens = assistant 回复的 token 数

8. context_window 与 max_tokens 的关系

每个模型有最大上下文窗口（context_window），规定了单次请求的总 token 上限：

• 输入 tokens + max_tokens ≤ context_window
• 如果超过，API 返回 400 Bad Request: max_tokens too large for model

# 假设某模型 context_window = 4096 tokens
你已经发送了 3500 tokens 的历史对话
那么 max_tokens 不能超过 596

payload = {
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "继续上文..."}],  # 假设含 3500 tokens
    "max_tokens": 596   # 4096 - 3500 = 596
}

三、错误处理与状态码

9. HTTP 状态码速查表

• 200 OK — 请求成功
• 400 Bad Request — 请求参数错误，如缺必填字段或值越界
• 401 Unauthorized — API Key 无效或未提供
• 403 Forbidden — 账户余额不足或无权限
• 429 Rate Limited — 请求频率超限，需退避重试
• 500 Internal Server Error — 服务器端错误，通常重试可解决

import time
import requests

def call_api_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://api.holysheep.ai/v1/chat/completions",
                headers={"Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY"},
                json={
                    "model": "deepseek-v3.2",
                    "messages": messages,
                    "max_tokens": 1000
                },
                timeout=30
            )
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                wait_time = 2 ** attempt  # 指数退避：1s, 2s, 4s
                print(f"频率限制，等待 {wait_time} 秒...")
                time.sleep(wait_time)
            elif response.status_code == 401:
                raise Exception("API Key 无效，请检查 YOUR_HOLYSHEEP_API_KEY")
            else:
                print(f"错误 {response.status_code}: {response.text}")
                
        except requests.exceptions.Timeout:
            print(f"请求超时，重试 {attempt + 1}/{max_retries}")
            
    return None

四、Embedding 与向量搜索术语

10. embedding 模型与维度

Embedding 将文本转换为向量，用于语义搜索、相似度匹配等场景。不同模型输出向量维度不同：

# 调用 HolySheep Embedding 接口
response = requests.post(
    "https://api.holysheep.ai/v1/embeddings",
    headers={
        "Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "text-embedding-3-large",
        "input": "这是一段用于生成向量的文本"
    }
)

data = response.json()
embedding_vector = data["data"][0]["embedding"]
print(f"向量维度: {len(embedding_vector)}")

11. cosine_similarity 余弦相似度

衡量两个向量相似程度，取值 -1 到 1，越接近 1 表示越相似。

import numpy as np

def cosine_similarity(a, b):
    a = np.array(a)
    b = np.array(b)
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

示例：比较两个文本的相似度
vec1 = [0.1, 0.3, 0.5, ...]  # "机器学习"
vec2 = [0.15, 0.25, 0.55, ...]  # "人工智能"
similarity = cosine_similarity(vec1, vec2)
print(f"相似度: {similarity:.4f}")

ข้อผิดพลาดที่พบบ่อยและวิธีแก้ไข

错误 1：401 Unauthorized — Invalid API Key

最常见的错误，通常是因为 key 未设置或格式错误。

# ❌ 错误写法
headers = {"Authorization": "YOUR_HOLYSHEEP_API_KEY"}  # 缺少 Bearer

✅ 正确写法
headers = {"Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY"}

如果不确定 key 是否正确，先测试连通性
test_response = requests.get(
    "https://api.holysheep.ai/v1/models",
    headers={"Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY"}
)
if test_response.status_code != 200:
    print("API Key 无效，请到 https://www.holysheep.ai/register 获取新密钥")

错误 2：400 Bad Request — Invalid JSON

请求体 JSON 格式错误，如多余逗号、缺少引号等。

# ❌ 常见 JSON 错误
json={
    "model": "gpt-4.1",      # 尾部多余逗号
    "messages": [...],       # JSON 中不能有尾随逗号
}

✅ 使用 Python dict 自动避免这类问题
payload = {
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "你好"}]
}

发送前可以验证 JSON
import json
json_str = json.dumps(payload, ensure_ascii=False)
print(f"JSON 长度: {len(json_str)} 字符")

错误 3：429 Rate Limit Exceeded

请求频率超过限制，需要实现指数退避重试机制。

import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

配置自动重试的 session
session = requests.Session()
retry_strategy = Retry(
    total=3,
    backoff_factor=1,         # 重试间隔：1s, 2s, 4s
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)

response = session.post(
    "https://api.holysheep.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY"},
    json={"model": "deepseek-v3.2", "messages": [{"role": "user", "content": "test"}], "max_tokens": 10}
)
print(response.status_code)

错误 4：ConnectionError — timeout

网络超时或服务器无响应，可通过设置合理的 timeout 捕获。

import requests
from requests.exceptions import ConnectTimeout, ReadTimeout

try:
    response = requests.post(
        "https://api.holysheep.ai/v1/chat/completions",
        headers={"Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY"},
        json={
            "model": "gemini-2.5-flash",
            "messages": [{"role": "user", "content": "Hello"}],
            "max_tokens": 100
        },
        timeout=(5, 30)  # (connect_timeout, read_timeout)
    )
except ConnectTimeout:
    print("无法连接到 API 服务器，请检查网络或 base_url")
except ReadTimeout:
    print("服务器响应超时，可能是模型处理时间过长，尝试减少 max_tokens")
except Exception as e:
    print(f"未知错误: {type(e).__name__}: {e}")

五、进阶概念速查

12. frequency_penalty 与 presence_penalty

• frequency_penalty — 降低已出现词汇的重复概率（-2.0 到 2.0）
• presence_penalty — 鼓励引入新话题（-2.0 到 2.0）

13. n 参数（completions 数量）

指定生成多少个独立回复，每个都会收费。注意不是并行执行，而是串行生成 n 个结果。

# 生成 3 个不同的回复（费用 × 3）
payload = {
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "给公司起个名字"}],
    "n": 3,
    "max_tokens": 50
}
响应中 choices 数组会包含 3 个元素

14. logit_bias（逻辑偏移）

强制或禁止某些 token 出现，token_id 从 tokenizer 获取。值 -100 表示强制禁止。

# 禁止 AI 输出 "不知道" 这个词
payload = {
    "model": "claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "你怎么看"}],
    "logit_bias": {
        "12345": -100  # 假设 "不知道" 的 token_id 是 12345
    }
}

六、HolySheep AI 定价对比

相比官方定价，HolySheep AI 可节省 85% 以上费用：

• GPT-4.1 — $8/MTok（官方 $60/MTok）
• Claude Sonnet 4.5 — $15/MTok（官方 $108/MTok）
• Gemini 2.5 Flash — $2.50/MTok（官方 $17.50/MTok）
• DeepSeek V3.2 — $0.42/MTok（官方 $2.80/MTok）

延迟低于 50ms，支持微信/支付宝充值，新用户注册即送免费额度。

总结

掌握这些 API 核心术语后，你应该能够：

• 正确配置请求参数，避免 400/401 错误
• 根据场景选择合适的 temperature 和 top_p
• 实现健壮的重试机制处理 429 和超时
• 优化 token 使用，降低 API 调用成本

建议收藏本文作为日常开发的参考手册，遇到不确定的参数时随时查阅。

👉 สมัคร HolySheep AI — รับเครดิตฟรีเมื่อลงทะเบียน ```