简介:本文面向零基础读者,讲清大模型应用的入门路径。读完后,你可以用 HTML、JavaScript、FastAPI 和 Uvicorn 搭出一个能对话的网页应用,并知道如何配置密钥、处理超时错误、估算调用成本以及选择合适的模型。
很多初学者一开始就去学深度学习、Transformer 和模型训练,学了几个月还做不出任何应用,信心也随之下降。对零基础读者来说,更务实的路线是先做出一个能用的应用:用网页收集用户输入,由后端调用模型,再把回答显示在页面上。
完整的学习顺序可以分为四步:
如果想在成熟的平台上练习,百度智能云千帆大模型平台提供大模型与 AI 原生应用的开发能力,适合作为学习和实验环境。本文涉及百度智能云产品链接,文中不列出具体价格,实际价格以官网和账单为准。
一个入门项目通常包含三部分:兼容 OpenAI 接口的模型服务、负责输入和展示的前端页面,以及用 Uvicorn 运行的后端服务。后端使用 FastAPI 接收前端请求,调用模型,再把结果返回给前端。
llm-demo/├── main.py├── .env├── .gitignore├── requirements.txt└── static/└── index.html
需要 Python 3.9 或更高版本。在项目目录中创建虚拟环境,可以避免和系统中其他项目的依赖版本冲突。
requirements.txt 内容如下:
fastapi>=0.110,<1.0uvicorn>=0.29,<1.0openai>=1.40,<2.0python-dotenv>=1.0,<2.0
执行以下命令创建环境并安装依赖:
python -m venv .venvsource .venv/bin/activate # Windows 使用 .venv\Scripts\activatepip install -r requirements.txt
import osfrom pathlib import Pathfrom dotenv import load_dotenvfrom fastapi import FastAPI, HTTPExceptionfrom fastapi.responses import HTMLResponsefrom openai import (OpenAI,APIError,APITimeoutError,AuthenticationError,NotFoundError,RateLimitError,)from pydantic import BaseModelload_dotenv()BASE_DIR = Path(__file__).resolve().parentapp = FastAPI()client = OpenAI(api_key=os.getenv("LLM_API_KEY"),base_url=os.getenv("LLM_BASE_URL"),timeout=30,max_retries=2,)class ChatRequest(BaseModel):message: str@app.get("/", response_class=HTMLResponse)def index():return (BASE_DIR / "static" / "index.html").read_text(encoding="utf-8")@app.post("/chat")def chat(payload: ChatRequest):message = payload.message.strip()if not message:raise HTTPException(status_code=400, detail="输入不能为空")try:response = client.chat.completions.create(model=os.getenv("LLM_MODEL", "default"),messages=[{"role": "user", "content": message}],)except APITimeoutError:raise HTTPException(status_code=504, detail="模型响应超时,请稍后重试")except AuthenticationError:raise HTTPException(status_code=500, detail="API Key 无效,请检查配置")except NotFoundError:raise HTTPException(status_code=500, detail="模型名称或接口地址不正确")except RateLimitError:raise HTTPException(status_code=429, detail="请求过于频繁,请稍后重试")except APIError:raise HTTPException(status_code=502, detail="模型服务异常")answer = response.choices[0].message.contentreturn {"answer": answer}
代码中的 detail 在本地调试时很有用,但它会把配置问题直接告诉访问页面的人。上线前应改为通用提示,并把详细错误写入服务端日志。
<!DOCTYPE html><html lang="zh-CN"><head><meta charset="UTF-8" /><title>大模型应用入门 Demo</title><style>body {font-family: Arial, sans-serif;max-width: 720px;margin: 40px auto;padding: 0 16px;}textarea {width: 100%;height: 120px;padding: 12px;font-size: 16px;}button {margin-top: 12px;padding: 10px 20px;font-size: 16px;cursor: pointer;}pre {margin-top: 20px;padding: 16px;background: #f5f5f5;white-space: pre-wrap;word-wrap: break-word;}</style></head><body><h1>大模型应用入门 Demo</h1><textarea id="input" placeholder="请输入你的问题"></textarea><br /><button onclick="sendMessage()">发送</button><pre id="output">等待模型回答...</pre><script>async function sendMessage() {const input = document.getElementById("input").value.trim();const output = document.getElementById("output");if (!input) {output.innerText = "请输入内容";return;}output.innerText = "正在请求模型...";const controller = new AbortController();const timer = setTimeout(() => controller.abort(), 40000);try {const response = await fetch("/chat", {method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify({ message: input }),signal: controller.signal});const data = await response.json();if (!response.ok) {output.innerText = "请求失败:" + (data.detail || response.status);return;}output.innerText = data.answer;} catch (err) {output.innerText = err.name === "AbortError"? "请求超时,请稍后重试": "网络错误,请检查服务是否已启动";} finally {clearTimeout(timer);}}</script></body></html>
在项目根目录创建 .env 文件,每行一个变量,等号两侧不要加空格:
LLM_API_KEY=你的API KeyLLM_BASE_URL=你的模型接口地址LLM_MODEL=你的模型名称
load_dotenv() 会读取这个文件。如果你已经在终端里用 export 设置了同名变量,系统默认不会用 .env 覆盖它。
密钥不能提交到 Git 仓库。执行下面的命令,把 .env 加入忽略列表:
echo ".env" >> .gitignoreecho ".venv/" >> .gitignore
如果密钥已经被提交过,只删除文件并不能消除风险,因为历史记录中仍然保留着它。正确做法是先在平台上撤销旧密钥,再生成新密钥。
uvicorn main:app --reload
--reload 只用于开发阶段,修改代码后服务会自动重启。
启动后,在浏览器打开 http://127.0.0.1:8000,输入问题并点击发送。也可以用下面的命令直接测试后端:
curl -X POST http://127.0.0.1:8000/chat \-H "Content-Type: application/json" \-d '{"message":"你好"}'
接口正常时返回的格式如下,其中 answer 的内容取决于模型:
{"answer": "你好!有什么可以帮你的吗?"}
小白入门时常见的误区是一开始就选参数最大、价格最高、能力最全的模型。实际开发中,模型选型应该围绕任务目标展开。
| 选型维度 | 说明 |
|---|---|
| 任务类型 | 聊天、摘要、翻译、代码、问答、结构化输出等 |
| 响应速度 | 实时对话更关注低延迟 |
| 上下文长度 | 长文档和多轮对话需要更长的上下文 |
| 调用成本 | Token 消耗会影响长期使用成本 |
| 稳定性 | 生产环境需要关注可用性和限流策略 |
| 接入复杂度 | 是否支持统一 API,是否便于迁移 |
选型时可以按下面四步操作:
单次调用的成本可以用下面的公式估算:
单次成本 ≈ 输入 Token 数 ÷ 1,000,000 × 输入单价 + 输出 Token 数 ÷ 1,000,000 × 输出单价
假设某模型的输入单价为每百万 Token 1 元,输出单价为每百万 Token 4 元。这些数字只用于演示计算,并非真实价格。一次请求输入 500 个 Token、输出 300 个 Token,单次成本约为 0.0017 元。每天 1000 次请求,每天约 1.7 元。
实际费用还可能受缓存、批量调用和阶梯计价的影响,最终以平台账单为准。百度智能云词元所可以查看模型列表和价格说明,入口为 https://cloud.baidu.com/product-s/token_exchange.html。
控制成本的常用方法包括:精简提示词、减少历史消息、避免重复传入大段资料、限制输出长度。
能跑通 Demo 只是第一步。要让应用真正服务于业务,还需要补齐下面几项能力。
API Key 不能写在前端 JavaScript 中,任何打开页面的人都能在浏览器里看到它。前端只请求自己的后端接口,后端通过环境变量或配置中心读取密钥。生产环境建议使用专门的密钥管理服务。
大模型接口可能因为网络波动或服务繁忙而变慢或失败。示例代码中已经设置了 timeout=30 和 max_retries=2。除此之外,还应该:
聊天机器人需要保存历史消息。常见做法有三种:
上线前建议记录用户输入、模型输出、请求耗时、Token 消耗和错误信息。有了这些数据,才能判断问题出在提示词、模型选择还是接口稳定性上。
如果你的项目已经在使用 OpenAI 接口,迁移到其他兼容平台时可以逐项检查:
base_url 是否已改为新平台的地址,路径前缀是否正确。model 是否已换成新平台提供的模型名称。choices 列表,但需要用真实请求确认字段。temperature 的取值区间和最大输出长度,不同平台可能不同。下面的节奏可以作为参考。每周投入的时间因人而异,可以按自己的进度调整。
目标:完成一个网页版问答 Demo。
目标:让回答更稳定,更符合业务需求。
目标:让模型基于私有资料回答问题。
目标:让模型不仅能回答,还能调用工具完成任务。
如果希望在理论和实践之间有系统的补充,可以参考百度智能云大模型培训服务。其内容包含通识课和实践课。
先看页面或接口返回的状态码,再对照下表排查:
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 401 或 AuthenticationError | API Key 错误或已过期 | 重新复制 Key,检查 .env 是否生效 |
| 404 或 NotFoundError | 模型名称或 base_url 写错 |
对照平台的模型列表和接口文档 |
| 429 或 RateLimitError | 请求频率过高或额度不足 | 降低请求频率,检查账户额度 |
| 504 或超时 | 模型响应慢或网络不稳定 | 换用响应更快的模型,检查网络 |
| 422 | 请求体缺少 message 字段 |
检查前端发送的 JSON 格式 |
通常是没有激活虚拟环境,或者没有安装依赖。先执行 source .venv/bin/activate,再执行 pip install -r requirements.txt。
打开浏览器的开发者工具,查看 Console 中的报错,再到 Network 面板确认 /chat 请求的状态码和返回内容。
小白入门大模型应用开发,可以先用 HTML、JavaScript、FastAPI 和 Uvicorn 做出一个能运行的问答页面。之后再按需学习提示词、上下文管理、RAG、Agent 和工程化部署。模型选型和成本估算放在第一个 Demo 跑通之后做,这时手里已经有真实的调用数据,决策会更有依据。