AI 应用开发

为什么需要框架 直接调用 LLM API 可以完成简单问答，但一旦涉及多轮工具调用、状态管理、多 Agent 协作，手写代码的复杂度会迅速上升。框架的价值在于提供标准化的抽象层。 主流框架简要对比 框架 定位 优势 局限 LangChain 通用 LLM 应用开发 生态最全，集成组件多 抽象层较重，调试复杂链路较麻烦 LlamaIndex 数据检索与 RAG 为核心 索引与检索能力强 Agent 能力相对偏弱 AutoGen 多 Agent 协作 天然支持多角色对话式协作 对单 Agent 简单任务偏重 原生 Function Calling 直接使用模型能力 轻量、可控性最高 需要自行实现状态管理 选型建议 简单问答 / 单轮工具调用：优先直接使用模型的 function calling 能力，避免引入不必要的框架开销 知识库问答类应用：LlamaIndex 在索引构建与检索优化上更专注 复杂多步骤任务编排：LangChain 的 LCEL（表达式语言）或 LangGraph 提供了较好的状态图抽象 需要多个专业角色协作（如“规划者 + 执行者 + 审核者”）：AutoGen 一类的多 Agent 框架更契合 一个最小 Agent 示例（伪代码） tools = [search_tool, calculator_tool] def run_agent(query): while True: response = llm.chat(messages, tools=tools) if response.tool_calls: for call in response.tool_calls: result = execute_tool(call) messages.append(tool_result(call, result)) else: return response.content 理解这个基本循环（LLM 决策 → 工具执行 → 结果回填 → 再决策）比死记框架 API 更重要，框架本质上都是在此基础上做工程化封装。 ...

结构化 Prompt 的基本框架 一个稳定可复用的 Prompt 通常包含以下几个部分： [角色设定] 你是一名资深的后端工程师 [任务描述] 请审查以下代码是否存在安全隐患 [输出约束] 以 JSON 格式输出，字段包括 issue、severity、suggestion [输入内容] {code} 将角色、任务、约束与输入明确分区，可以显著降低模型输出格式不稳定的概率。 强制结构化输出 对接下游程序时，建议明确要求 JSON 并给出 schema 示例： 请仅输出如下格式的 JSON，不要包含任何多余文字： { "summary": "string", "risk_level": "low | medium | high", "actions": ["string"] } 如果使用支持 function calling 或 structured output 的模型/框架，优先使用原生能力而非纯文本约束，稳定性更高。 思维链（CoT）引导 对于推理类任务，显式要求模型分步思考能提升准确率： 请先列出解决该问题需要的关键步骤，再逐步推导，最后给出结论。 需要注意的是，面向最终用户展示的产品通常应隐藏推理过程，只暴露结论，避免冗长输出影响体验。 Few-shot 示例的选择 示例数量并非越多越好，2~4 个高质量示例通常优于大量低质量示例 示例应覆盖边界情况（如空输入、异常格式），而不仅是“标准”场景 示例格式必须与期望输出格式完全一致，包括缩进和标点 常见反模式 在 Prompt 中堆砌矛盾指令（如同时要求“详细”又要求“简洁”） 过度依赖否定式指令（“不要做 X”），效果通常弱于正向描述期望行为 忽略模型的上下文长度限制，导致关键指令被截断 小结 Prompt 工程的本质是通过清晰的结构和约束，降低模型输出的不确定性，使其更适配工程化的下游调用。

RAG 的基本流程 一个典型 RAG 系统由四个阶段组成：文档切分 → 向量化 → 检索 → 生成。 原始文档 → Chunking → Embedding → 向量数据库 ↓ 用户问题 → Embedding → 向量检索 → Top-K 片段 → 拼接 Prompt → LLM 生成答案 文档切分策略 切分粒度直接影响检索质量： 固定长度切分：实现简单，但可能截断语义完整的段落 按语义切分：借助标题、段落结构切分，效果更好但实现复杂 滑动窗口重叠：相邻 chunk 间保留 10%~20% 重叠，缓解边界信息丢失 一般建议 chunk 大小控制在 300~800 token 之间，具体需结合模型上下文长度与检索精度需求测试确定。 向量数据库选型 方案 特点 适用场景 Milvus 分布式、功能全面 大规模生产环境 Qdrant 轻量、Rust 实现、性能好 中小规模自建 Chroma 极简易用 原型开发、本地实验 pgvector 复用现有 PostgreSQL 已有 PG 基础设施的团队 检索质量优化 混合检索：结合稀疏检索（BM25）与稠密向量检索，弥补语义检索对专有名词、编号类查询不敏感的问题 Rerank：检索出 Top-20 后，用专门的 rerank 模型重新排序取 Top-5，显著提升精度 查询改写：对用户原始问题做扩展或拆分，尤其适合处理多跳问题 常见陷阱 忽略 chunk 元数据（来源、章节）会导致答案缺乏可追溯性 检索结果未去重，可能造成同一内容多次占用上下文 未设置相似度阈值，低相关片段也被强行拼入 Prompt，反而干扰生成质量 小结 RAG 并非简单的“检索 + 拼接”，切分策略、检索方式与重排序环节的组合调优才是决定系统效果的关键。

目标 让本地部署的模型可以像调用 OpenAI 官方 API 一样被现有代码无缝调用，只需替换 base_url 和 api_key。 启动服务 vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \ --quantization awq \ --served-model-name my-local-llm \ --api-key sk-local-demo-key \ --port 8000 --served-model-name 决定客户端请求中 model 字段应填写的值；--api-key 用于简单鉴权。 Python 客户端调用 from openai import OpenAI client = OpenAI( base_url="http://127.0.0.1:8000/v1", api_key="sk-local-demo-key", ) resp = client.chat.completions.create( model="my-local-llm", messages=[{"role": "user", "content": "用一句话解释向量数据库"}], ) print(resp.choices[0].message.content) 使用 systemd 常驻服务 避免通过 nohup 挂起进程，推荐用 systemd 管理： # /etc/systemd/system/vllm.service [Unit] Description=vLLM Inference Server After=network.target [Service] User=vllmuser WorkingDirectory=/opt/vllm ExecStart=/opt/vllm/vllm-env/bin/vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ --port 8000 Restart=always RestartSec=5 [Install] WantedBy=multi-user.target sudo systemctl daemon-reload sudo systemctl enable --now vllm 通过 Nginx 反向代理暴露服务 生产环境不建议直接暴露 8000 端口，应通过 Nginx 做 TLS 终止与限流，具体配置可参考本站《Nginx 反向代理与 HTTPS 配置》一文。 ...

影响显存占用的关键参数 参数 作用 建议值 --gpu-memory-utilization GPU 显存预留比例 单卡场景 0.85~0.9 --max-model-len 最大上下文长度 按实际业务设置，避免过大浪费 --max-num-seqs 同时处理的最大序列数 根据显存余量调整 --block-size PagedAttention 分页大小 默认 16，一般无需更改 --swap-space CPU 侧交换空间(GB) 显存紧张时可设置 4~8 量化降低显存占用 对 7B 级别模型，FP16 大约需要 14GB 显存用于权重本身，加上 KV Cache 后往往超过消费级显卡容量。使用 AWQ 或 GPTQ 4-bit 量化可将权重显存需求降低到原来的 1/4 左右： vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ --quantization awq 提升吞吐的关键：Continuous Batching vLLM 默认启用连续批处理，无需手动配置。但可以通过 --max-num-batched-tokens 控制单次调度的 token 总量，值越大吞吐越高，但延迟波动也会增加，需要根据 SLA 要求权衡。 多卡场景：张量并行 vllm serve meta-llama/Llama-3-70B-Instruct \ --tensor-parallel-size 4 \ --gpu-memory-utilization 0.9 --tensor-parallel-size 需与实际 GPU 数量匹配，且各卡显存尽量一致，否则会以最小显存的卡为瓶颈。 ...

为什么选择 vLLM 在自建大模型推理服务时，显存利用率和吞吐量往往是最大的瓶颈。传统的 HuggingFace transformers 推理方式在处理并发请求时，KV Cache 的管理效率较低，容易出现显存碎片化。vLLM 通过 PagedAttention 机制，将 KV Cache 按照固定大小的“页”进行管理，类似操作系统的虚拟内存分页，从而大幅提升显存利用率与并发吞吐能力。 核心特性 PagedAttention：按页管理 KV Cache，减少显存浪费 Continuous Batching：动态批处理，新请求可以在旧请求未完成时插入 OpenAI 兼容 API：可直接替换 OpenAI SDK 的 base_url 多种量化支持：AWQ、GPTQ、FP8 等，降低显存占用 安装 python3 -m venv vllm-env source vllm-env/bin/activate pip install vllm 对于显存有限的轻量环境，建议使用较小参数量模型并结合量化版本，例如 Qwen2.5-7B-Instruct-AWQ。 启动一个推理服务 vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \ --quantization awq \ --max-model-len 8192 \ --gpu-memory-utilization 0.85 \ --port 8000 启动后即可通过标准 OpenAI 接口调用： curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen/Qwen2.5-7B-Instruct-AWQ", "messages": [{"role": "user", "content": "你好"}] }' 小结 vLLM 的轻量化并不意味着功能阉割，而是在保持高吞吐的同时降低了部署门槛。后续文章将深入探讨显存调优、批处理参数以及生产环境的服务化实践。