LLM应用集成实战：基于FastAPI构建Xfwl4智能问答服务

最近在做大模型应用落地时一个很常见的困惑是项目里既要接大语言模型又要处理业务系统的接入、调度、资源配置但网上资料大多停留在单点调用缺少一套从概念、框架选型到实际部署的完整链路。加上不少团队内部项目代号比较独特比如本文中的Xfwl4外部资料几乎搜不到遇到问题只能自己啃源码、看日志、慢慢试。这篇文章就把这套经验整理出来围绕“LLM 应用集成 Xfwl4 示例项目”展开从背景概念、环境准备、框架集成到底层原理、完整实战和排错思路都过一遍。无论是刚开始接触 LLM 应用的开发者还是需要在业务中接入大模型能力的后端工程师都可以按这套流程走一遍。1. 背景与核心概念1.1 LLM 到底是什么LLM 是 Large Language Model 的缩写中文叫大语言模型。它的核心能力是基于海量文本数据训练出来的“文本生成模型”给定一段输入模型会根据学习到的概率分布生成后续文本。与传统 NLP 模型相比LLM 的优势在于具备上下文理解能力能处理较长的对话或任务描述支持零样本和少样本学习很多任务不需要单独训练模型通过 Prompt 工程就能改变模型行为适合快速迭代在总结、翻译、代码生成、知识问答、信息抽取等场景表现稳定。用一个不太严谨但比较好理解的比喻LLM 更像一个“读过海量资料的实习生”你对它说清楚任务和要求它能给出结果但需要你验证它的输出是否正确。1.2 Xfwl4 在本文中的定位Xfwl4并不是一个大语言模型的标准名称也不是某个公开框架的固定代号。在实际项目里这类名称通常是内部服务名、模块名或项目代号。本文中Xfwl4会作为“基于 LLM 能力封装的一个业务服务示例项目”来使用。这样做的好处是贴近真实工程场景LLM 本身只负责文本推理业务系统需要自己做 Prompt 构建、接口封装、结果解析、异常兜底、权限控制、日志记录和部署管理。Xfwl4就是承载这些能力的示例服务。所以本文并不是介绍某个特定源码而是把“LLM 服务如何接入业务系统”这件事拆开讲清楚。你可以把Xfwl4替换成自己项目里的任何服务名称。1.3 为什么需要把 LLM 封装成服务很多初学 LLM 的开发者会直接在 Python 脚本里调用模型 API比如response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)这样写本身没问题但在生产项目中会遇到几个问题无法复用多个业务模块都要调用模型时每个模块各自写一遍请求逻辑后期改模型或调参数很痛苦。缺少统一管控API Key 散落在各个代码文件里模型版本、token 使用量、调用频率都没有统一管理。错误处理不完善网络超时、模型限流、返回格式异常等情况没有统一处理策略。与业务耦合严重业务代码里到处都是 Prompt 拼接和模型相关逻辑一旦换模型厂商改动范围会非常大。所以在正式项目中更推荐的做法是封装一个统一的模型调用层或独立服务。Xfwl4就是这样的一个示例服务对外提供 HTTP 接口或工具类业务方只需要传入业务参数不需要关心模型是怎么调用的。1.4 常见应用场景LLM 业务化的常见场景包括智能客服根据用户问题检索知识库再结合 LLM 生成答案文档助手对长文档进行摘要、问答、内容抽取代码助手根据需求描述生成代码片段或对代码进行 review数据分析助手把自然语言问题转换为 SQL 查询内容生产工具生成新闻稿、营销文案、标题建议企业知识库问答基于私有文档的 RAG 问答系统。本文示例会围绕一个相对轻量的“智能问答/指令处理”服务展开但底层的设计思路可以迁移到其他场景。2. 环境准备与版本说明2.1 运行环境本文示例以常见环境为例重点演示设计思路。你本地的实际版本可以根据项目情况调整。项目建议环境操作系统Windows 10/11、macOS、LinuxCentOS 7/Ubuntu 20.04均可Python3.9 / 3.10 / 3.11 均可建议 3.10依赖管理pip 或 poetryHTTP 框架FastAPI 或 Flask本文示例用 FastAPILLM 模型支持 OpenAI 兼容接口的模型或本地部署模型API 测试工具Postman / Apifox / curl需要注意的是不同 LLM 模型的接口格式可能存在差异。本文示例代码会采用目前生态兼容性较高的 OpenAI 兼容调用方式这样即使你本地部署的是 Ollama、vLLM 等服务的模型接口也能通过统一格式接入。2.2 安装依赖先创建一个项目目录并初始化虚拟环境mkdir xfwl4-demo cd xfwl4-demo python -m venv venvWindows 下激活虚拟环境venv\Scripts\activatemacOS / Linux 下激活虚拟环境source venv/bin/activate然后安装依赖pip install fastapi uvicorn openai pydantic requests python-dotenv这里解释一下各个依赖的作用fastapi构建 HTTP 接口服务uvicornFastAPI 的 ASGI 服务器用来启动服务openai官方 Python SDK也可用于调用兼容 OpenAI 格式的本地模型服务pydantic参数校验和数据结构定义requests备用 HTTP 请求库方便测试其他接口python-dotenv读取.env配置文件管理密钥和参数。如果你的网络环境无法直接安装这些包可以使用国内 pip 镜像例如pip install -i https://pypi.tuna.tsinghua.edu.cn/simple fastapi uvicorn openai pydantic requests python-dotenv2.3 模型服务准备为了让示例代码真正运行起来需要有一个可用的模型服务。常见的两种方式方式一使用云端模型 API。直接使用模型厂商提供的 API Key在.env文件中配置API_BASE和API_KEY。方式二使用本地模型服务。比如使用 Ollama 本地部署 Qwen、Llama 等模型启动后默认监听本地端口。Ollama 兼容 OpenAI 接口可以用openaiSDK 直接调用。本地调用示例ollama pull qwen2.5:7b ollama serve启动后模型服务的地址通常是http://localhost:11434/v1。如果你选择用本地模型还需要准备足量的内存和显卡资源。7B 级别的模型量化后通常需要 6GB 到 8GB 显存或者 16GB 以上内存的 CPU 推理方案。3. LLM 框架与调用方式拆解3.1 为什么要使用 LLM 框架开发中常见的“LLM 框架”指两类东西一类是 LangChain、LlamaIndex 这类应用开发框架提供 Prompt 管理、文档加载、向量检索、Agent 等能力另一类是模型推理和部署框架如 vLLM、Ollama、FastChat 等。对于业务项目而言不一定要引入重量级框架。如果只是调用模型 API 并处理返回结果原生 SDK 就已经够用。引入框架的前提是项目需要处理复杂 Prompt 流程需要多步工具调用Function Calling需要文档检索和知识库增强RAG团队需要统一封装 Prompt 和模型交互逻辑。从工程角度来说我的建议是先不用框架把流程跑通再根据复杂度决定是否引入框架。直接写一层简单的封装服务往往更可控、更容易排查问题。这就是Xfwl4示例项目采用轻量封装的原因。3.2 OpenAI 兼容接口的调用流程目前绝大多数模型服务都支持 OpenAI 兼容接口核心调用参数如下参数含义示例model模型名称qwen2.5:7b、gpt-3.5-turbomessages对话消息列表每条包含role和contenttemperature采样温度控制随机性0.2 到 0.8max_tokens最大生成 token 数512stream是否流式返回False一个最简单的调用示例如下from openai import OpenAI client OpenAI( base_urlhttp://localhost:11434/v1, api_keyollama ) resp client.chat.completions.create( modelqwen2.5:7b, messages[ {role: system, content: 你是一个简洁的中文助手。}, {role: user, content: 介绍一下大语言模型。}, ], temperature0.3, max_tokens512, ) print(resp.choices[0].message.content)需要注意的点api_key即使本地模型不需要也要传一个非空字符串否则 SDK 可能报错base_url要指向服务地址并且以/v1结尾messages中的role支持system、user、assistant三种角色。3.3 Prompt 设计的基本原则LLM 输出的质量很大程度上取决于 Prompt 的质量。几条经验明确角色告诉模型它是谁、要以什么身份回答。给出约束限制输出格式、长度、语气。提供示例需要结构化输出时给出 Few-shot 示例。拆分任务复杂任务拆成多个简单步骤避免在一个 Prompt 里堆要求。防止注入用户输入中可能包含恶意指令要把用户输入视为数据而不是指令。示例你是 Xfwl4 系统的智能助手。请根据用户问题输出 JSON 格式答案只输出 JSON 对象不要额外解释。 问题{user_input} 输出格式{answer: 你的回答, confidence: 0.0到1.0的置信度}3.4 LLM 与其他服务是否必须部署在同一台机器上这是很多初学者困惑的问题特别是接触 ComfyUI图像生成工具和 LLM 时会问“ComfyUI 与 LLM 是否必须在同一台电脑上”。答案是不需要。ComfyUI 主要承担图像生成工作流运行的是 Stable Diffusion 类模型LLM 承担文本理解和生成。两者本质上都是模型服务只要通过 HTTP API 或微服务方式通信就可以分布在不同的机器上。甚至在实际项目中ComfyUI 服务跑在带 GPU 的机器上LLM 服务跑在另一台 GPU 机器或云端前端再调用业务网关这种架构非常常见。示例部署结构用户请求 → Xfwl4 网关服务 → LLM 服务机器 A ↓ 需要出图时 ↓ 请求 ComfyUI API机器 B或同一台机器的另一块GPU所以结论是在部署层面ComfyUI 与 LLM 可以分离部署只需要网络可达并处理好接口鉴权和超时即可。这个原则同样适用于其他独立模型服务。4. 完整实战搭建 Xfwl4 智能问答服务下面我们通过一个完整示例把前面讲的核心概念串起来。这个示例会实现两个功能提供一个 HTTP 接口/api/chat接收用户问题返回 LLM 生成的答案支持简单的“意图判断”如果用户请求包含“生成图片”则调用 ComfyUI 接口触发图像生成返回任务 ID。生产环境可以根据需要扩展更多模块但整体架构不变。4.1 创建项目结构xfwl4-demo/ ├── .env ├── requirements.txt ├── app/ │ ├── __init__.py │ ├── main.py │ ├── config.py │ ├── llm_client.py │ ├── schemas.py │ └── routers/ │ ├── __init__.py │ └── chat.py └── run.sh4.2 添加依赖与配置requirements.txt内容fastapi0.111.0 uvicorn0.30.1 openai1.35.3 pydantic2.8.2 python-dotenv1.0.1 requests2.32.3注意版本号会持续更新实际安装时可以先用最新版如果出现兼容问题再调整。.env文件内容# 模型服务配置 LLM_BASE_URLhttp://localhost:11434/v1 LLM_API_KEYollama LLM_MODELqwen2.5:7b LLM_TEMPERATURE0.3 LLM_MAX_TOKENS512 # ComfyUI 服务配置用于图片生成场景 COMFYUI_BASE_URLhttp://localhost:81884.3 编写配置模块文件路径app/config.pyimport os from dotenv import load_dotenv load_dotenv() class Settings: 全局配置类从环境变量或 .env 文件读取配置。 def __init__(self): self.llm_base_url os.getenv(LLM_BASE_URL, http://localhost:11434/v1) self.llm_api_key os.getenv(LLM_API_KEY, ollama) self.llm_model os.getenv(LLM_MODEL, qwen2.5:7b) self.llm_temperature float(os.getenv(LLM_TEMPERATURE, 0.3)) self.llm_max_tokens int(os.getenv(LLM_MAX_TOKENS, 512)) self.comfyui_base_url os.getenv(COMFYUI_BASE_URL, http://localhost:8188) settings Settings()4.4 编写 LLM 客户端文件路径app/llm_client.pyfrom openai import OpenAI from app.config import settings class LLMClient: 封装 LLM 调用逻辑包括对话接口和流式接口。 def __init__(self): self.client OpenAI( base_urlsettings.llm_base_url, api_keysettings.llm_api_key, timeout60, ) def chat(self, system_prompt: str, user_message: str) - str: 普通对话接口返回完整文本。 try: resp self.client.chat.completions.create( modelsettings.llm_model, messages[ {role: system, content: system_prompt}, {role: user, content: user_message}, ], temperaturesettings.llm_temperature, max_tokenssettings.llm_max_tokens, ) return resp.choices[0].message.content.strip() except Exception as e: # 统一异常包装方便上层捕获 raise RuntimeError(fLLM 调用失败: {e}) def chat_stream(self, system_prompt: str, user_message: str): 流式对话接口适合打字机效果。 stream self.client.chat.completions.create( modelsettings.llm_model, messages[ {role: system, content: system_prompt}, {role: user, content: user_message}, ], temperaturesettings.llm_temperature, max_tokenssettings.llm_max_tokens, streamTrue, ) for chunk in stream: delta chunk.choices[0].delta if delta and delta.content: yield delta.content llm_client LLMClient()这里把异常统一包装成RuntimeError这样接口层可以统一捕获并返回友好的错误信息不会让底层 SDK 的异常直接暴露给调用方。4.5 编写数据模型文件路径app/schemas.pyfrom pydantic import BaseModel, Field class ChatRequest(BaseModel): message: str Field(..., description用户输入的问题, min_length1) system_prompt: str Field( default你是一个智能助手请尽量简洁、准确地回答问题。, description系统提示词可选 ) class ChatResponse(BaseModel): answer: str model: str need_image: bool False image_task_id: str | None None4.6 编写路由接口文件路径app/routers/chat.pyimport requests from fastapi import APIRouter, HTTPException from app.config import settings from app.llm_client import llm_client from app.schemas import ChatRequest, ChatResponse router APIRouter(prefix/api, tags[chat]) # 模拟一个最简单的意图判断函数 def need_generate_image(message: str) - bool: 如果用户输入包含图片相关关键词就触发图片生成流程。 keywords [生成图片, 画一张, 插图, 图片, 图] return any(kw in message for kw in keywords) def trigger_comfyui(image_prompt: str) - str: 调用 ComfyUI 接口触发图片生成。 实际项目中需要根据 ComfyUI 的工作流 API 格式做适配 这里只演示调用思路。 # 这里的 API 地址和 payload 需要根据 ComfyUI 实际工作流调整 payload { prompt: image_prompt, client_id: xfwl4-demo, } try: resp requests.post( f{settings.comfyui_base_url}/prompt, jsonpayload, timeout30, ) resp.raise_for_status() return resp.json().get(prompt_id, unknown) except Exception as e: raise HTTPException(status_code502, detailfComfyUI 调用失败: {e}) router.post(/chat, response_modelChatResponse) def chat(request: ChatRequest): try: answer llm_client.chat(request.system_prompt, request.message) except RuntimeError as e: raise HTTPException(status_code500, detailstr(e)) image_task_id None if need_generate_image(request.message): # 简单起见直接把用户输入作为图片 prompt 传递 image_task_id trigger_comfyui(request.message) return ChatResponse( answeranswer, modelsettings.llm_model, need_imageimage_task_id is not None, image_task_idimage_task_id, )这个示例中trigger_comfyui函数是一个简化实现。实际调用 ComfyUI 时需要先了解其 WebSocket API 和/prompt接口的 payload 结构。新手可以先不接 ComfyUI而是把image_task_id写死测试流程。4.7 编写服务入口文件路径app/main.pyfrom fastapi import FastAPI from app.routers import chat app FastAPI( titleXfwl4 LLM API Service, description基于 LLM 的智能问答与任务分发服务, version0.1.0, ) app.include_router(chat.router) app.get(/health) def health_check(): return {status: ok, service: xfwl4}4.8 启动服务在项目根目录创建run.shLinux/macOS#!/bin/bash source venv/bin/activate uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadWindows PowerShell 下直接执行venv\Scripts\activate uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload启动后访问http://localhost:8000/docs可以看到 FastAPI 自动生成的接口文档页面。4.9 验证接口使用 curl 测试curl -X POST http://localhost:8000/api/chat \ -H Content-Type: application/json \ -d {\message\: \介绍一下 Xfwl4 项目\}预期返回是一个 JSON 对象类似于{ answer: Xfwl4 是一个基于 LLM 的智能问答服务示例项目它封装了大模型调用逻辑并提供 HTTP 接口供业务系统接入。, model: qwen2.5:7b, need_image: false, image_task_id: null }如果调用包含“生成图片”的请求curl -X POST http://localhost:8000/api/chat \ -H Content-Type: application/json \ -d {\message\: \帮我生成一张风景图\}need_image字段会变成trueimage_task_id会返回 ComfyUI 的任务编号。4.10 完整代码清单如果你只想快速跑起来直接按下面的文件树创建即可。所有代码段拼起来就是一个最小可运行的 LLM 服务。我建议至少手动敲一遍理解每一行的作用再复制到项目里。5. 常见问题与排查思路5.1 LLM 调用报 404 或连接失败问题现象常见原因解决思路调用 LLM 时返回 404base_url拼接错误检查 base_url 是否以/v1结尾连接超时模型服务没有启动或地址错误先用浏览器或 curl 访问模型服务地址确认可达401 鉴权失败API Key 不正确或本地服务不需要鉴权但填了错误 key本地 Ollama 服务统一填ollama即可显存不足本地模型太大或没有用量化版本换更小模型或开启 CPU 推理降低并发排查顺序建议先确认模型服务进程是否存活使用 curl 直接调用模型接口看是否正常再排查应用代码中的base_url和api_key最后看应用日志中的完整异常栈。5.2 返回结果不稳定同一个问题多次调用答案可能不同。这通常是温度参数造成的。temperature越大生成结果越随机越小结果越确定。如果需要稳定答案把temperature调到 0.1 到 0.3 之间。如果业务对答案格式要求严格更要使用结构化 Prompt 约束输出并在代码里做格式校验。比如要求模型输出 JSON但模型偶尔会夹杂多余文字可以加一步后处理截取“第一个{” 到最后一个}”之间的内容再解析。5.3 中文回答经常出现乱码或缺少标点多见于本地模型未配置正确系统提示词的情况。可以在system_prompt中加入“请使用规范中文回答不要使用 Markdown 表格以外的特殊符号”。如果使用的是最新模型一般不会出现严重乱码问题。5.4 调用 ComfyUI 接口失败如果示例代码里的 ComfyUI 调用失败最常见的原因是 payload 格式不对。ComfyUI 的/prompt接口需要完整的工作流对象而不是简单一句提示词。解决方法是在 ComfyUI 中手动导入工作流并将其导出为 API 格式 JSON把 JSON 作为模板保存到项目里调用时动态替换其中的 Prompt 内容字段再 POST 到/prompt接口。5.5 FastAPI 接口返回 500 但没有详细日志这种情况通常是因为代码中使用了raise HTTPException之外的方式处理异常或者底层异常被 FastAPI 默认捕获。建议在开发环境打开 Debug 日志或直接让异常抛出router.post(/chat, response_modelChatResponse) def chat(request: ChatRequest): answer llm_client.chat(request.system_prompt, request.message) ...开发阶段不要先捕获所有异常让调用栈暴露出来更容易定位问题。生产环境再统一捕获并写入日志。6. 最佳实践与工程建议6.1 配置管理不要把 API Key 和模型地址硬编码在代码里。推荐的做法是使用.env文件 配置类线上环境通过环境变量注入敏感信息。如果使用 Docker 部署可以通过.env文件或配置中心统一管理。示例LLM_BASE_URL${LLM_BASE_URL} LLM_API_KEY${LLM_API_KEY} LLM_MODEL${LLM_MODEL}6.2 统一 Prompt 管理实际项目中Prompt 不应该散落在路由代码里。建议单独建一个prompts.py文件维护所有 Prompt 模板后续做版本管理和优化也方便。例如CHAT_SYSTEM_PROMPT 你是一个智能助手请保持回答简洁准确。 IMAGE_PROMPT_TEMPLATE 请根据以下需求生成图片描述{user_input}6.3 异常处理与重试LLM 服务常常因为网络波动或限流导致偶发失败。建议对 LLM 调用增加重试机制但要注意设置合理的最大重试次数和退避策略。简单重试示例import time def chat_with_retry(system_prompt: str, user_message: str, max_retries: int 3): for attempt in range(max_retries): try: return llm_client.chat(system_prompt, user_message) except RuntimeError: if attempt max_retries - 1: raise time.sleep(2 ** attempt) return 6.4 日志记录LLM 调用日志至少要记录以下信息请求 ID用户 ID 或业务 ID模型名称输入内容和输出内容注意脱敏token 消耗调用耗时是否重试成功。这样可以方便后续做成本统计、效果分析和问题回溯。6.5 安全边界LLM 应用是安全风险比较高的场景需要重点注意Prompt 注入用户输入可能携带恶意指令。处理原则是把用户输入当作数据不要当作指令执行。输出内容校验模型输出可能包含不当内容或错误信息生产环境建议增加敏感词过滤或人工审核环节。API 鉴权不要把模型服务的 API 直接暴露给公网。外部请求统一走业务网关网关做身份认证和限流。成本控制加上单用户调用频率限制和每日成本阈值。6.6 性能优化如果并发量较大建议使用异步接口FastAPI 的async def使用连接池复用模型服务连接使用缓存把高频的相同问题答案缓存起来对长文本任务使用流式输出降低首字延迟本地模型服务单独部署避免和业务服务抢资源。下面是一个简单的缓存思路from functools import lru_cache lru_cache(maxsize128) def get_llm_answer(system_prompt: str, user_message: str) - str: return llm_client.chat(system_prompt, user_message)注意lru_cache适合完全相同输入的缓存适合 FAQ 场景不适合个性化对话。6.7 可维护性在代码结构上建议把LLM 客户端、Prompt 管理、业务逻辑、接口层分层解耦。这样后续换模型、改 Prompt、调整业务逻辑时改动范围都能控制在小范围内。以本文为例接口层app/routers/chat.py模型层app/llm_client.py配置层app/config.py业务层后续根据实际需求新增加app/services/目录。6.8 关于 ComfyUI 与 LLM 的部署建议再次强调ComfyUI 和 LLM 不必部署在同一台机器上。实际项目中更推荐LLM 服务单独部署承载高并发文本请求ComfyUI 部署在带有 GPU 的机器上承担图像生成任务通过消息队列或 HTTP 接口异步传递任务避免图像生成阻塞 LLM 主链路。如果两者部署在同一台机器上要注意显存隔离。多个模型同时常驻显存可能导致资源不足建议按需加载或使用Ollama的模型并发策略。也可以在业务层做排队控制。7. 总结与后续方向这篇文章从一个具体的示例项目Xfwl4出发梳理了大语言模型应用接入业务系统的完整链路。核心内容包括LLM 的基本概念和应用场景如何封装一个统一的模型调用服务FastAPI 接口如何对接 LLM如何通过 HTTP API 与其他模型服务如 ComfyUI通信常见错误的排查思路和最佳实践。如果你在团队里要维护这类 LLM 服务下一步可以重点做这几件事建立一份llm wiki把团队常用的模型版本、Prompt 模板、调用参数、成本口径沉淀下来根据业务需要引入 LangChain 或 LlamaIndex 等 LLM 框架处理更复杂的检索增强生成RAG流程完善模型服务的可观测性接入监控、日志链路和成本分析逐步从同步调用改为异步任务队列提升系统整体吞吐量。代码可以在本地直接运行建议你根据自己的模型服务配置调整.env先跑通一个最小问答接口再扩展图片生成或其他业务模块。动手改一遍比只看文章效果好得多。后面遇到问题也可以对照“常见问题与排查思路”这一节逐个排查。