大模型应用开发：从 API 到 RAG

大模型应用并不神秘：本质上就是「把用户的输入，加上我们准备好的上下文，送给模型，再把模型返回的结果呈现出来」。这篇笔记从最朴素的接口调用讲起，一路走到带检索增强（RAG）的应用。

一、先跑通第一个接口

不管用哪家服务，第一步都是用 API Key 发一个 HTTP 请求。下面用 Python 演示最小可运行版本：

import os, requests

resp = requests.post(
    "https://api.example.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "model": "mini",
        "messages": [{"role": "user", "content": "用一句话解释什么是 RAG"}],
    },
)
print(resp.json()["choices"][0]["message"]["content"])

二、别把密钥写进代码

密钥一旦提交到仓库，基本就等于公开了。请用环境变量或密钥管理，并在 .gitignore 里忽略本地配置文件。上面的示例已经用 os.environ 读取，是正确的做法。

三、RAG 是怎么工作的

RAG（Retrieval-Augmented Generation，检索增强生成）解决的是「模型不知道你私有的资料」这个问题。流程可以拆成三步：

• 检索（Retrieve）：用户提问时，先从知识库里找出最相关的几段文本；
• 增强（Augment）：把检索到的文本拼进提示词，作为上下文；
• 生成（Generate）：让模型基于这些上下文作答，而非凭空编造。

def answer(question):
    hits = search(question, top_k=3)        # 1. 检索
    context = "\n".join(h["text"] for h in hits)
    prompt = f"参考以下资料回答问题：\n{context}\n\n问题：{question}"  # 2. 增强
    return chat(prompt)                      # 3. 生成

四、对话要带历史

多轮对话的核心是维护一个 messages 数组，每轮把用户消息和助手回复依次追加进去。注意历史会占用 token，必要时做截断或摘要。

五、几个常见的坑

1. 上下文截断：长文档超了上下文窗口，先做切块（chunk）再检索；
2. 计费：输入输出都按 token 计费，缓存高频提示词能省不少；
3. 流式输出：用 SSE / 流式接口，体验比「转圈半天再整段蹦出来」好得多。