本节课目标：

彻底看懂一次最基础的大模型 API 调用。

你会明白：

• 为什么要调用 /chat/completions

• system prompt 到底是什么

• messages 为什么是数组

• temperature、max_tokens 有什么作用

• 返回结果为什么要一层层取 choices[0]["message"]["content"]

• RAG 后续为什么一定离不开这套结构

---

一、为什么这一课非常重要？

很多人在学习 RAG 的时候，直接开始：

• 向量数据库

• embedding

• chunk

• rerank

• agent

• 工作流

结果最后：

连最基础的大模型对话接口都没真正理解。

实际上：

RAG 的本质，最后还是：

把“检索出来的内容”塞进 prompt
再调用 chat/completions

所以：

如果你连 chat/completions 都没理解，后面很多知识都会变成“背概念”。

这一课，我们只做一件事：

把一次大模型对话 API 完全拆开。

---

二、本节课最终代码

下面这段代码，就是本节课最核心的内容。

import requests


def chat_completion(system_prompt, question):
    resp = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": CHAT_MODEL,
            "messages": [
                {
                    "role": "system",
                    "content": system_prompt
                },
                {
                    "role": "user",
                    "content": question
                }
            ],
            "temperature": 0.3,
            "max_tokens": 1000
        },
        timeout=30
    )

    if resp.status_code != 200:
        raise Exception(f"chat API 调用失败")

    return resp.json()["choices"][0]["message"]["content"]

很多初学者看到这里会觉得：

这不就是 requests.post 吗？

但实际上：

这里面包含了整个 AI 应用开发的核心逻辑。

---

三、chat/completions 到底是什么？

这一句：

/chat/completions

是整个大模型“对话能力”的入口。

你可以理解成：

这是 AI 的聊天窗口

我们把消息发过去。

模型再把回答返回回来。

本质上：

它就是一个 HTTP 接口。

所以你会看到：

requests.post(...)

因为我们本质上是在：

向 AI 服务器发送一次 POST 请求。

---

四、BASE_URL 是什么？

代码：

f"{BASE_URL}/chat/completions"

这里的 BASE_URL：

通常是模型平台的地址。

比如：

https://api.openai.com/v1

或者：

https://dashscope.aliyuncs.com/compatible-mode/v1

再或者：

https://api.deepseek.com/v1

拼接后：

https://api.xxx.com/v1/chat/completions

这就是完整接口。

---

五、headers 为什么必须写？

代码：

headers={
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

这里面有两个关键内容。

---

1）Authorization

"Authorization": f"Bearer {API_KEY}"

这是：

身份认证。

你可以理解成：

登录 AI 平台的钥匙

没有 API_KEY：

服务器根本不知道你是谁。

所以：

很多新手第一次调用失败：

其实不是代码问题。

而是：

API_KEY 错了。

---

2）Content-Type

"Content-Type": "application/json"

这是告诉服务器：

我发送的数据是 JSON 格式

否则：

服务器可能无法正确解析。

这是 HTTP 请求中的标准写法。

---

六、json 参数才是真正的核心

这一段：

json={
    ...
}

才是真正决定：

AI 如何思考。

里面每个字段都非常重要。

---

七、model 是什么？

代码：

"model": CHAT_MODEL

这里指定：

你要调用哪个模型。

例如：

"gpt-4o-mini"

或者：

"deepseek-chat"

或者：

"qwen-max"

不同模型：

• 能力不同

• 价格不同

• 速度不同

• 上下文长度不同

所以：

model 本质上是：

选择 AI 大脑。

---

八、messages 才是灵魂

代码：

"messages": [
    {
        "role": "system",
        "content": system_prompt
    },
    {
        "role": "user",
        "content": question
    }
]

很多人学 AI 最大的问题：

就是只会写 prompt。

但不知道：

为什么 prompt 要放在 messages 里面。

---

九、为什么 messages 是数组？

因为：

大模型本质上是“多轮对话”。

例如：

用户：你好
AI：你好
用户：帮我写 Python
AI：好的

其实会变成：

messages = [
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好"},
    {"role": "user", "content": "帮我写 Python"}
]

模型会读取：

整个历史对话。

所以：

messages 必须是数组。

因为里面会不断追加聊天记录。

---

十、role 到底是什么意思？

每条消息都必须有：

role

因为模型需要知道：

这句话是谁说的。

目前最常见的有三种角色：

role	含义
system	系统身份设定
user	用户输入
assistant	AI 回复

---

十一、system prompt 是什么？

代码：

{
    "role": "system",
    "content": system_prompt
}

这是整个 AI 应用开发里最重要的东西之一。

system prompt：

决定 AI 是谁。

比如：

你是一个资深 Python 专家

或者：

你是一个 RAG 架构师

或者：

你只能根据知识库回答

你会发现：

AI 的行为会完全改变。

所以：

很多 AI 项目：

真正的壁垒其实是：

prompt engineering

而不是代码。

---

十二、user role 是什么？

代码：

{
    "role": "user",
    "content": question
}

这里就是：

用户真正的问题。

例如：

"content": "请解释什么是 RAG"

模型会结合：

• system prompt

• user question

• 历史上下文

一起生成回答。

---

十三、temperature 是什么？

代码：

"temperature": 0.3

这是：

控制模型发散程度。

可以理解成：

AI 的随机性

---

temperature 越低

例如：

0.1

特点：

• 更稳定

• 更严谨

• 更像固定答案

• 更适合 RAG

• 更适合知识问答

---

temperature 越高

例如：

1.2

特点：

• 更有创造力

• 更发散

• 更容易胡说

• 更适合小说

• 更适合创意写作

---

为什么 RAG 通常 temperature 很低？

因为：

RAG 的目标是：

根据知识库准确回答。

不是让 AI 自由发挥。

所以：

通常会设置：

0.1 ~ 0.5

---

十四、max_tokens 是什么？

代码：

"max_tokens": 1000

这是：

最大生成长度。

很多人误以为：

token = 单词

其实不准确。

对于中文：

一个汉字通常也会占 token。

---

为什么必须限制？

因为：

token = 钱。

生成越长：

• 越贵

• 越慢

• 越容易跑偏

所以：

生产环境里：

必须控制 token。

---

十五、timeout 为什么重要？

代码：

timeout=30

意思是：

30 秒没返回就超时

为什么必须写？

因为：

AI 接口可能卡死。

如果不设置 timeout：

程序可能会一直等待。

这是生产环境里非常危险的。

---

十六、为什么要检查 status_code

代码：

if resp.status_code != 200:
    raise Exception("chat API 调用失败")

因为：

并不是所有请求都会成功。

例如：

• API_KEY 错误

• 余额不足

• 网络异常

• 请求太频繁

• 模型不存在

这时候：

服务器会返回错误码。

所以：

必须做异常处理。

这是很多新手最容易忽略的问题。

---

十七、最难理解的一行代码

代码：

resp.json()["choices"][0]["message"]["content"]

很多初学者看到这里直接懵。

但其实：

本质就是一层层取 JSON。

---

十八、AI 返回的数据结构到底长什么样？

实际上：

服务器返回的大概是：

{
    "choices": [
        {
            "message": {
                "content": "你好，我是 AI"
            }
        }
    ]
}

所以：

---

第一步

resp.json()

把响应转成 Python 字典。

---

第二步

["choices"]

取出：

choices

得到：

[
    {
        "message": {
            "content": "你好，我是 AI"
        }
    }
]

这是一个列表。

---

第三步

[0]

取第一个回答。

因为：

有些模型可能一次返回多个候选答案。

所以：

choices 是数组。

---

第四步

["message"]

得到：

{
    "content": "你好，我是 AI"
}

---

第五步

["content"]

最终得到：

"你好，我是 AI"

这才是真正的模型回复。

---

十九、这一课和 RAG 的关系

你现在看到的：

只是普通聊天。

但 RAG 会多一步：

先检索知识库

然后：

把检索结果拼接进 prompt

最后：

还是调用：

/chat/completions

例如：

system_prompt = f"""
你必须根据以下知识库回答：

{context}
"""

这就是：

RAG 的核心思想。

所以：

这一课其实是：

后面所有 AI 应用开发的基础。

---

二十、完整运行示例

下面给大家一个可以直接运行的版本。

import requests

BASE_URL = "https://api.openai.com/v1"
API_KEY = "你的API_KEY"
CHAT_MODEL = "gpt-4o-mini"


def chat_completion(system_prompt, question):
    resp = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": CHAT_MODEL,
            "messages": [
                {
                    "role": "system",
                    "content": system_prompt
                },
                {
                    "role": "user",
                    "content": question
                }
            ],
            "temperature": 0.3,
            "max_tokens": 1000
        },
        timeout=30
    )

    if resp.status_code != 200:
        raise Exception(resp.text)

    return resp.json()["choices"][0]["message"]["content"]


answer = chat_completion(
    "你是一个 Python 专家",
    "请解释什么是 RAG"
)

print(answer)

---

二十一、本节课你必须真正理解的内容

不要死记代码。

真正要理解的是：

模块	本质
chat/completions	AI 对话入口
system prompt	AI 身份设定
user	用户问题
messages	历史上下文
temperature	随机性控制
max_tokens	输出长度控制
choices	模型候选答案

当你真正理解这些以后：

你会发现：

RAG、Agent、工作流、本地知识库，本质上都是在“操控 prompt”。

---

二十二、下一课预告

下一节课我们会正式进入：

RAG 的第一步：Embedding

你会真正理解：

• 为什么文本可以变成向量

• embedding 到底是什么

• 为什么向量能表示语义

• 相似度搜索为什么能找到“意思相近”的内容

• RAG 为什么离不开向量数据库

这是从“调用 AI”走向“构建 AI 系统”的真正开始。

---

最后

如果这篇文章对你有帮助，欢迎：点赞、收藏、关注

后面会继续更新：

• RAG 全流程

• 向量数据库

• Agent

• LangChain

• LangGraph

• MCP

• AI 工作流

• 本地知识库

• 企业级 RAG 架构