小白做大模型应用:从网页Demo到选型指南

作者:搬砖的石头2026.11.17 03:44浏览量:0

简介:本文面向零基础读者,讲清大模型应用的入门路径。读完后,你可以用 HTML、JavaScript、FastAPI 和 Uvicorn 搭出一个能对话的网页应用,并知道如何配置密钥、处理超时错误、估算调用成本以及选择合适的模型。

一、先跑通“模型调用加网页交互”

很多初学者一开始就去学深度学习、Transformer 和模型训练,学了几个月还做不出任何应用,信心也随之下降。对零基础读者来说,更务实的路线是先做出一个能用的应用:用网页收集用户输入,由后端调用模型,再把回答显示在页面上。

完整的学习顺序可以分为四步:

  1. 先学会调用大模型 API,理解请求、响应、Token 和上下文长度等基本概念。
  2. 再做简单的网页应用,让用户在页面里提问并看到回答。
  3. 然后学习应用编排,包括提示词模板、多轮对话、知识库和工具调用。
  4. 最后深入具体场景,例如 RAG、Agent、企业知识库和智能客服。

如果想在成熟的平台上练习,百度智能云千帆大模型平台提供大模型与 AI 原生应用的开发能力,适合作为学习和实验环境。本文涉及百度智能云产品链接,文中不列出具体价格,实际价格以官网和账单为准。

二、最小项目:HTML、JavaScript 与 Uvicorn

一个入门项目通常包含三部分:兼容 OpenAI 接口的模型服务、负责输入和展示的前端页面,以及用 Uvicorn 运行的后端服务。后端使用 FastAPI 接收前端请求,调用模型,再把结果返回给前端。

1. 项目结构

  1. llm-demo/
  2. ├── main.py
  3. ├── .env
  4. ├── .gitignore
  5. ├── requirements.txt
  6. └── static/
  7. └── index.html

2. 环境准备

需要 Python 3.9 或更高版本。在项目目录中创建虚拟环境,可以避免和系统中其他项目的依赖版本冲突。

requirements.txt 内容如下:

  1. fastapi>=0.110,<1.0
  2. uvicorn>=0.29,<1.0
  3. openai>=1.40,<2.0
  4. python-dotenv>=1.0,<2.0

执行以下命令创建环境并安装依赖:

  1. python -m venv .venv
  2. source .venv/bin/activate # Windows 使用 .venv\Scripts\activate
  3. pip install -r requirements.txt

3. 后端:main.py

  1. import os
  2. from pathlib import Path
  3. from dotenv import load_dotenv
  4. from fastapi import FastAPI, HTTPException
  5. from fastapi.responses import HTMLResponse
  6. from openai import (
  7. OpenAI,
  8. APIError,
  9. APITimeoutError,
  10. AuthenticationError,
  11. NotFoundError,
  12. RateLimitError,
  13. )
  14. from pydantic import BaseModel
  15. load_dotenv()
  16. BASE_DIR = Path(__file__).resolve().parent
  17. app = FastAPI()
  18. client = OpenAI(
  19. api_key=os.getenv("LLM_API_KEY"),
  20. base_url=os.getenv("LLM_BASE_URL"),
  21. timeout=30,
  22. max_retries=2,
  23. )
  24. class ChatRequest(BaseModel):
  25. message: str
  26. @app.get("/", response_class=HTMLResponse)
  27. def index():
  28. return (BASE_DIR / "static" / "index.html").read_text(encoding="utf-8")
  29. @app.post("/chat")
  30. def chat(payload: ChatRequest):
  31. message = payload.message.strip()
  32. if not message:
  33. raise HTTPException(status_code=400, detail="输入不能为空")
  34. try:
  35. response = client.chat.completions.create(
  36. model=os.getenv("LLM_MODEL", "default"),
  37. messages=[{"role": "user", "content": message}],
  38. )
  39. except APITimeoutError:
  40. raise HTTPException(status_code=504, detail="模型响应超时,请稍后重试")
  41. except AuthenticationError:
  42. raise HTTPException(status_code=500, detail="API Key 无效,请检查配置")
  43. except NotFoundError:
  44. raise HTTPException(status_code=500, detail="模型名称或接口地址不正确")
  45. except RateLimitError:
  46. raise HTTPException(status_code=429, detail="请求过于频繁,请稍后重试")
  47. except APIError:
  48. raise HTTPException(status_code=502, detail="模型服务异常")
  49. answer = response.choices[0].message.content
  50. return {"answer": answer}

代码中的 detail 在本地调试时很有用,但它会把配置问题直接告诉访问页面的人。上线前应改为通用提示,并把详细错误写入服务端日志。

4. 前端:static/index.html

  1. <!DOCTYPE html>
  2. <html lang="zh-CN">
  3. <head>
  4. <meta charset="UTF-8" />
  5. <title>大模型应用入门 Demo</title>
  6. <style>
  7. body {
  8. font-family: Arial, sans-serif;
  9. max-width: 720px;
  10. margin: 40px auto;
  11. padding: 0 16px;
  12. }
  13. textarea {
  14. width: 100%;
  15. height: 120px;
  16. padding: 12px;
  17. font-size: 16px;
  18. }
  19. button {
  20. margin-top: 12px;
  21. padding: 10px 20px;
  22. font-size: 16px;
  23. cursor: pointer;
  24. }
  25. pre {
  26. margin-top: 20px;
  27. padding: 16px;
  28. background: #f5f5f5;
  29. white-space: pre-wrap;
  30. word-wrap: break-word;
  31. }
  32. </style>
  33. </head>
  34. <body>
  35. <h1>大模型应用入门 Demo</h1>
  36. <textarea id="input" placeholder="请输入你的问题"></textarea>
  37. <br />
  38. <button onclick="sendMessage()">发送</button>
  39. <pre id="output">等待模型回答...</pre>
  40. <script>
  41. async function sendMessage() {
  42. const input = document.getElementById("input").value.trim();
  43. const output = document.getElementById("output");
  44. if (!input) {
  45. output.innerText = "请输入内容";
  46. return;
  47. }
  48. output.innerText = "正在请求模型...";
  49. const controller = new AbortController();
  50. const timer = setTimeout(() => controller.abort(), 40000);
  51. try {
  52. const response = await fetch("/chat", {
  53. method: "POST",
  54. headers: { "Content-Type": "application/json" },
  55. body: JSON.stringify({ message: input }),
  56. signal: controller.signal
  57. });
  58. const data = await response.json();
  59. if (!response.ok) {
  60. output.innerText = "请求失败:" + (data.detail || response.status);
  61. return;
  62. }
  63. output.innerText = data.answer;
  64. } catch (err) {
  65. output.innerText = err.name === "AbortError"
  66. ? "请求超时,请稍后重试"
  67. : "网络错误,请检查服务是否已启动";
  68. } finally {
  69. clearTimeout(timer);
  70. }
  71. }
  72. </script>
  73. </body>
  74. </html>

5. 配置密钥

在项目根目录创建 .env 文件,每行一个变量,等号两侧不要加空格:

  1. LLM_API_KEY=你的API Key
  2. LLM_BASE_URL=你的模型接口地址
  3. LLM_MODEL=你的模型名称

load_dotenv() 会读取这个文件。如果你已经在终端里用 export 设置了同名变量,系统默认不会用 .env 覆盖它。

密钥不能提交到 Git 仓库。执行下面的命令,把 .env 加入忽略列表:

  1. echo ".env" >> .gitignore
  2. echo ".venv/" >> .gitignore

如果密钥已经被提交过,只删除文件并不能消除风险,因为历史记录中仍然保留着它。正确做法是先在平台上撤销旧密钥,再生成新密钥。

6. 启动与验证

  1. uvicorn main:app --reload

--reload 只用于开发阶段,修改代码后服务会自动重启。

启动后,在浏览器打开 http://127.0.0.1:8000,输入问题并点击发送。也可以用下面的命令直接测试后端:

  1. curl -X POST http://127.0.0.1:8000/chat \
  2. -H "Content-Type: application/json" \
  3. -d '{"message":"你好"}'

接口正常时返回的格式如下,其中 answer 的内容取决于模型:

  1. {"answer": "你好!有什么可以帮你的吗?"}

三、模型选型与成本估算

小白入门时常见的误区是一开始就选参数最大、价格最高、能力最全的模型。实际开发中,模型选型应该围绕任务目标展开。

选型维度 说明
任务类型 聊天、摘要、翻译、代码、问答、结构化输出等
响应速度 实时对话更关注低延迟
上下文长度 长文档和多轮对话需要更长的上下文
调用成本 Token 消耗会影响长期使用成本
稳定性 生产环境需要关注可用性和限流策略
接入复杂度 是否支持统一 API,是否便于迁移

选型时可以按下面四步操作:

  1. 在平台的模型列表中记录候选模型的名称、上下文长度、输入单价和输出单价。不同平台的计费单位不同,常见的是每百万 Token 或每千 Token,读价格前先确认单位。
  2. 准备 20 条左右的测试问题,覆盖你的真实业务场景。
  3. 用同一组问题分别调用候选模型,记录回答质量、响应时间和 Token 用量。
  4. 按成本公式估算费用,再结合回答质量和速度做决定。

单次调用的成本可以用下面的公式估算:

  1. 单次成本 ≈ 输入 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 到可用:入门后必须补的工程细节

能跑通 Demo 只是第一步。要让应用真正服务于业务,还需要补齐下面几项能力。

1. 密钥安全

API Key 不能写在前端 JavaScript 中,任何打开页面的人都能在浏览器里看到它。前端只请求自己的后端接口,后端通过环境变量或配置中心读取密钥。生产环境建议使用专门的密钥管理服务。

2. 超时与重试

大模型接口可能因为网络波动或服务繁忙而变慢或失败。示例代码中已经设置了 timeout=30 和 max_retries=2。除此之外,还应该:

  • 给用户明确的错误提示,不要让页面一直停在“正在请求”。
  • 对常见问题缓存答案,模型暂时不可用时可以返回缓存结果。
  • 失败时提示用户稍后再试,而不是直接报错。

3. 多轮对话管理

聊天机器人需要保存历史消息。常见做法有三种:

  • 只保留最近 N 轮对话,超出部分丢弃。
  • 对更早的历史消息做摘要压缩,保留关键信息。
  • 把长期知识放入知识库,按问题检索后再拼接到提示词中,而不是全部塞进上下文。

4. 日志与评估

上线前建议记录用户输入、模型输出、请求耗时、Token 消耗和错误信息。有了这些数据,才能判断问题出在提示词、模型选择还是接口稳定性上。

5. 从 OpenAI 接口迁移

如果你的项目已经在使用 OpenAI 接口,迁移到其他兼容平台时可以逐项检查:

  • base_url 是否已改为新平台的地址,路径前缀是否正确。
  • model 是否已换成新平台提供的模型名称。
  • API Key 是否来自新平台,环境变量是否已更新。
  • 响应结构是否一致。多数兼容接口仍返回 choices 列表,但需要用真实请求确认字段。
  • 参数范围是否相同,例如 temperature 的取值区间和最大输出长度,不同平台可能不同。

五、四周学习参考节奏

下面的节奏可以作为参考。每周投入的时间因人而异,可以按自己的进度调整。

第 1 周:跑通最小项目

目标:完成一个网页版问答 Demo。

  • HTML 和 JavaScript 基础。
  • Python 基础。
  • FastAPI 的基本用法,以及 Uvicorn 的启动方式。
  • 大模型 API 的基本调用。

第 2 周:提示词与对话管理

目标:让回答更稳定,更符合业务需求。

  • 提示词设计和系统提示词。
  • 多轮对话的上下文管理。
  • 输出格式控制。
  • 错误处理与重试。

rag-">第 3 周:RAG 应用

目标:让模型基于私有资料回答问题。

  • 文档解析和文本切分。
  • 向量化与向量检索。
  • 把检索结果拼接到提示词中。

agent-">第 4 周:Agent 与工具调用

目标:让模型不仅能回答,还能调用工具完成任务。

  • 工具调用和函数调用。
  • 任务拆解与多步骤流程。
  • 简单 Agent 的设计方法。

如果希望在理论和实践之间有系统的补充,可以参考百度智能云大模型培训服务。其内容包含通识课和实践课。

六、常见问题排查

1. 调用模型失败

先看页面或接口返回的状态码,再对照下表排查:

现象 常见原因 处理方法
401 或 AuthenticationError API Key 错误或已过期 重新复制 Key,检查 .env 是否生效
404 或 NotFoundError 模型名称或 base_url 写错 对照平台的模型列表和接口文档
429 或 RateLimitError 请求频率过高或额度不足 降低请求频率,检查账户额度
504 或超时 模型响应慢或网络不稳定 换用响应更快的模型,检查网络
422 请求体缺少 message 字段 检查前端发送的 JSON 格式

2. 启动时报 ModuleNotFoundError

通常是没有激活虚拟环境,或者没有安装依赖。先执行 source .venv/bin/activate,再执行 pip install -r requirements.txt。

3. 页面没有反应

打开浏览器的开发者工具,查看 Console 中的报错,再到 Network 面板确认 /chat 请求的状态码和返回内容。

4. 回答速度慢

  • 选择响应更快的模型。
  • 缩短输入上下文。
  • 使用流式输出,让文字逐步显示。
  • 对常见问题做缓存。

5. 成本过高

  • 减少不必要的历史消息。
  • 对长文档先做摘要,再交给模型。
  • 限制输出长度。
  • 按任务选择不同规格的模型。
  • 定期统计 Token 消耗。

6. 回答效果不稳定

  • 在系统提示词中明确角色、任务和限制。
  • 给出几个输入和输出的示例。
  • 限制输出格式,例如要求返回 JSON。
  • 对关键事实增加核验步骤。
  • 建立测试问题集,每次修改后都重新评估。

七、总结

小白入门大模型应用开发,可以先用 HTML、JavaScript、FastAPI 和 Uvicorn 做出一个能运行的问答页面。之后再按需学习提示词、上下文管理、RAG、Agent 和工程化部署。模型选型和成本估算放在第一个 Demo 跑通之后做,这时手里已经有真实的调用数据,决策会更有依据。