AI应用构建与部署实战：从环境搭建到生产部署的完整指南

在AI技术浪潮席卷各行各业的今天无论是个人开发者还是企业团队都希望将大模型、智能体Agent或RAG检索增强生成等前沿AI能力快速转化为实际可用的应用。然而从“跑通一个Demo”到“构建一个稳定、可维护、可扩展的AI应用”中间横亘着巨大的工程鸿沟。许多开发者卡在环境配置、服务部署、性能优化和持续迭代等环节网上资料虽多却零散难以形成闭环。本文将系统性地拆解构建与部署AI应用所需的核心技能栈从环境隔离、模型服务化、应用开发到生产部署与监控提供一套完整的实战指南与避坑方案。无论你是想本地部署ChatGLM、Qwen还是基于FastAPI构建RAG服务或是用Docker封装整个AI应用都能从中找到清晰的路径和可复用的代码。1. 核心概念与技能全景图在深入实操之前我们首先要厘清“构建”和“部署”AI应用分别指什么以及它们所依赖的核心技能有哪些。1.1 构建 vs. 部署AI应用的生命周期构建Building指的是AI应用的开发阶段核心是将AI能力如大模型、向量检索、智能体逻辑集成到一个可运行的软件系统中。这包括环境搭建创建隔离、可复现的Python/Conda环境。模型获取与加载下载预训练模型并使用合适的框架如Transformers, llama.cpp, vLLM加载。应用逻辑开发编写业务代码例如用FastAPI/Flask构建API设计RAG的检索与生成流程实现Agent的决策链。测试与验证确保功能正确性能达标。部署Deployment指的是将构建好的应用发布到目标环境本地服务器、云主机、容器平台并使其持续、稳定地对外提供服务的过程。这包括服务封装将应用及其所有依赖打包如使用Docker。资源编排配置计算资源CPU/GPU、内存和存储。服务暴露通过Web服务器如Nginx、API网关或负载均衡器如ELB对外提供访问。运维监控设置日志、指标收集如Prometheus和健康检查确保应用高可用。1.2 构建部署AI应用的六大核心技能基于当前社区的热点如Ollama本地部署、Dify、FastAPI RAG、Docker部署我们可以梳理出以下六大不可或缺的技能领域环境与依赖管理使用Conda、Docker实现环境隔离与复现避免“在我机器上能跑”的困境。模型服务化掌握将大模型转化为API服务的能力涉及Ollama、vLLM、Transformers等工具。后端API开发使用FastAPI、Flask等框架构建稳健、高效的Web API作为AI能力的前端接口。应用架构设计针对RAG、Agent等复杂场景设计合理的系统架构包括向量数据库、工作流引擎等。容器化与编排使用Docker将应用标准化并利用Docker Compose或Kubernetes进行多服务编排。生产环境运维配置反向代理、负载均衡、监控告警保障服务的稳定性、安全性与可观测性。接下来我们将围绕这六大技能结合具体工具和代码示例展开详细讲解。2. 环境准备与基础工具链一个可复现的环境是后续所有工作的基石。我们将从最基础的Python环境管理开始。2.1 Python环境隔离Conda实战强烈建议使用Conda或venv进行环境隔离。这里以Conda为例。# 1. 创建并激活一个名为ai-app的Python 3.10环境 conda create -n ai-app python3.10 -y conda activate ai-app # 2. 安装基础AI开发库 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 根据CUDA版本调整 pip install transformers accelerate sentence-transformers pip install fastapi uvicorn[standard] pydantic pip install langchain langchain-community pip install docker python-dotenv # 3. 验证安装 python -c import torch; print(fPyTorch版本: {torch.__version__}, CUDA可用: {torch.cuda.is_available()}) python -c import fastapi; print(fFastAPI版本: {fastapi.__version__})为什么这么做固定Python版本和库版本可以最大程度避免因版本冲突导致的诡异错误。accelerate库可以帮助优化模型加载和推理。2.2 版本控制与项目结构使用Git进行版本控制并建立一个清晰的项目结构。my-ai-app/ ├── .gitignore ├── .env.example # 环境变量示例 ├── requirements.txt # Python依赖 ├── Dockerfile # Docker构建文件 ├── docker-compose.yml # 服务编排 ├── app/ # 应用核心代码 │ ├── __init__.py │ ├── main.py # FastAPI应用入口 │ ├── models/ # 数据模型 │ ├── services/ # 业务逻辑如模型调用、RAG │ ├── routers/ # API路由 │ └── utils/ # 工具函数 ├── configs/ # 配置文件 ├── scripts/ # 部署或运维脚本 ├── tests/ # 测试代码 └── README.md使用pip freeze requirements.txt生成依赖文件并在Dockerfile或新的环境中使用pip install -r requirements.txt来安装。3. 模型服务化从本地加载到API提供让模型能够被应用代码调用是构建AI应用的第一步。根据模型大小和硬件条件有不同方案。3.1 方案一使用Ollama部署本地大模型推荐给初学者和轻量场景Ollama极大地简化了本地大模型的下载、运行和管理特别适合快速原型验证。# 在Linux/macOS上安装Ollama curl -fsSL https://ollama.com/install.sh | sh # 拉取并运行一个模型例如Qwen2.5:7B ollama pull qwen2.5:7b ollama run qwen2.5:7b # 此时模型已在本地运行并提供了一个简单的聊天接口 # 更重要的是Ollama提供了兼容OpenAI API的接口 # 默认在 http://localhost:11434 提供API服务在你的Python应用中可以像调用OpenAI一样调用本地模型# app/services/llm_service.py import openai # 配置客户端指向本地的Ollama服务 client openai.OpenAI( base_urlhttp://localhost:11434/v1, api_keyollama, # ollama的API key可以任意填写非空即可 ) def chat_with_ollama(messages, modelqwen2.5:7b): try: response client.chat.completions.create( modelmodel, messagesmessages, streamFalse, ) return response.choices[0].message.content except Exception as e: return f模型调用失败: {str(e)} # 使用示例 if __name__ __main__: messages [{role: user, content: 你好请介绍一下你自己。}] answer chat_with_ollama(messages) print(answer)优势开箱即用无需处理复杂的模型加载和GPU内存管理。局限对模型格式有要求定制化程度相对较低。3.2 方案二使用Transformers库直接加载适合深度定制如果你需要对模型推理过程有完全控制权或使用Ollama不支持的模型可以使用Hugging Face Transformers。# app/services/custom_llm_service.py from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline import torch class CustomModelService: def __init__(self, model_name_or_pathQwen/Qwen2.5-7B-Instruct): self.device cuda if torch.cuda.is_available() else cpu print(f正在加载模型到设备: {self.device}) # 加载tokenizer和模型 self.tokenizer AutoTokenizer.from_pretrained(model_name_or_path, trust_remote_codeTrue) self.model AutoModelForCausalLM.from_pretrained( model_name_or_path, torch_dtypetorch.float16 if self.device cuda else torch.float32, device_mapauto if self.device cuda else None, trust_remote_codeTrue ) # 构建文本生成管道 self.pipe pipeline( text-generation, modelself.model, tokenizerself.tokenizer, device0 if self.device cuda else -1, ) print(模型加载完毕。) def generate(self, prompt, max_new_tokens512): messages [{role: user, content: prompt}] # 使用ChatML格式或模型要求的格式 text self.tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) outputs self.pipe( text, max_new_tokensmax_new_tokens, do_sampleTrue, temperature0.7, top_p0.9, ) return outputs[0][generated_text][len(text):] # 返回生成的回复部分 # 使用示例注意首次运行需要下载模型耗时较长 if __name__ __main__: service CustomModelService() # 可以替换为本地路径如 ./models/Qwen2.5-7B-Instruct result service.generate(中国的首都是哪里) print(result)关键参数解释torch_dtypetorch.float16: 使用半精度浮点数可显著减少GPU内存占用。device_mapauto: 让Transformers自动将模型层分配到可用的GPU设备上对于大模型非常有用。trust_remote_codeTrue: 对于Qwen等模型需要信任其自定义代码。3.3 方案三使用vLLM进行高性能推理适合生产环境vLLM是一个专为LLM推理设计的高吞吐量、内存高效的推理引擎特别适合需要高并发服务的生产场景。# 安装vLLM pip install vllm启动一个独立的vLLM服务# 使用OpenAI兼容的API服务器启动模型 python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b \ --api-key token-abc123 \ --port 8000然后在你的应用中可以像调用OpenAI API一样调用这个服务# 配置客户端指向vLLM服务 client openai.OpenAI( base_urlhttp://localhost:8000/v1, api_keytoken-abc123, ) # 后续调用方式与Ollama示例完全相同vLLM的核心优势PagedAttention高效管理注意力机制的键值缓存大幅提升吞吐量。连续批处理动态将多个请求的推理过程合并提高GPU利用率。开源且活跃由加州大学伯克利分校等机构开发社区支持好。4. 构建AI应用后端以FastAPI实现RAG问答系统掌握了模型服务化之后我们将其集成到一个完整的Web应用中。这里以构建一个本地知识库问答系统RAG为例。4.1 项目初始化与依赖创建项目并安装额外依赖。pip install fastapi uvicorn[standard] pip install sentence-transformers # 用于文本向量化 pip install chromadb # 轻量级向量数据库 pip install pypdf # 用于解析PDF pip install tiktoken # 用于文本分词估算token4.2 核心模块设计我们的RAG系统包含以下模块文档加载与切分读取PDF/TXT文件并将其切分成适合检索的片段Chunk。向量化与存储将文本片段转换为向量并存入向量数据库。检索与生成根据用户问题检索相关文档片段并将其与问题一起提交给LLM生成答案。4.2.1 文档处理服务# app/services/document_processor.py from typing import List import os from pypdf import PdfReader from langchain.text_splitter import RecursiveCharacterTextSplitter class DocumentProcessor: def __init__(self, chunk_size500, chunk_overlap50): self.text_splitter RecursiveCharacterTextSplitter( chunk_sizechunk_size, chunk_overlapchunk_overlap, length_functionlen, separators[\n\n, \n, 。, , , , , , ] ) def load_and_split_pdf(self, pdf_path: str) - List[str]: 加载PDF文件并切分成文本块 if not os.path.exists(pdf_path): raise FileNotFoundError(f文件不存在: {pdf_path}) reader PdfReader(pdf_path) full_text for page in reader.pages: full_text page.extract_text() \n # 使用LangChain的文本分割器 chunks self.text_splitter.split_text(full_text) return chunks def load_and_split_text(self, text: str) - List[str]: 直接切分文本 return self.text_splitter.split_text(text)4.2.2 向量数据库服务# app/services/vector_store.py import chromadb from chromadb.config import Settings from sentence_transformers import SentenceTransformer import numpy as np from typing import List, Dict, Any class VectorStoreService: def __init__(self, persist_directory./chroma_db, embedding_model_nameall-MiniLM-L6-v2): # 初始化嵌入模型 self.embedding_model SentenceTransformer(embedding_model_name) # 初始化Chroma客户端设置持久化路径 self.client chromadb.PersistentClient( pathpersist_directory, settingsSettings(anonymized_telemetryFalse) # 禁用匿名遥测 ) # 获取或创建集合类似于数据库的表 self.collection self.client.get_or_create_collection( nameknowledge_base, metadata{description: 存储知识文档的向量集合} ) def create_embeddings(self, texts: List[str]) - List[List[float]]: 将文本列表转换为向量列表 # SentenceTransformer直接返回numpy数组需转换为list embeddings self.embedding_model.encode(texts) return embeddings.tolist() def add_documents(self, documents: List[str], metadatas: List[Dict[str, Any]] None): 向向量数据库添加文档 if not documents: return # 生成嵌入向量 embeddings self.create_embeddings(documents) # 生成唯一的ID ids [fdoc_{i} for i in range(len(documents))] # 如果没有提供元数据创建默认元数据 if metadatas is None: metadatas [{source: uploaded_doc} for _ in documents] # 添加到集合 self.collection.add( embeddingsembeddings, documentsdocuments, metadatasmetadatas, idsids ) print(f成功添加 {len(documents)} 个文档到向量数据库。) def search_similar(self, query: str, n_results: int 3) - List[Dict]: 检索与查询最相似的文档 # 将查询文本向量化 query_embedding self.create_embeddings([query])[0] # 执行相似性搜索 results self.collection.query( query_embeddings[query_embedding], n_resultsn_results, include[documents, metadatas, distances] ) # 整理返回结果 retrieved_docs [] if results[documents]: for i in range(len(results[documents][0])): retrieved_docs.append({ content: results[documents][0][i], metadata: results[metadatas][0][i], distance: results[distances][0][i] }) return retrieved_docs4.2.3 RAG问答服务# app/services/rag_service.py from typing import List, Dict from app.services.vector_store import VectorStoreService from app.services.llm_service import chat_with_ollama # 假设使用3.1节的Ollama服务 class RAGService: def __init__(self, vector_store: VectorStoreService): self.vector_store vector_store def answer_question(self, question: str, use_context: bool True) - Dict: 基于RAG回答用户问题 if not use_context: # 直接调用LLM不使用检索 answer chat_with_ollama([{role: user, content: question}]) return { answer: answer, source_documents: [], is_rag: False } # 1. 检索相关文档 retrieved_docs self.vector_store.search_similar(question, n_results3) if not retrieved_docs: # 如果没有检索到相关文档直接回答 answer chat_with_ollama([{role: user, content: question}]) return { answer: answer, source_documents: [], is_rag: False, note: 未检索到相关文档直接生成回答。 } # 2. 构建包含上下文的提示词 context_text \n\n---\n\n.join([doc[content] for doc in retrieved_docs]) prompt f请基于以下提供的上下文信息回答问题。如果上下文信息不足以回答问题请直接说明你不知道不要编造信息。 上下文信息 {context_text} 问题{question} 请用中文回答 # 3. 调用LLM生成答案 answer chat_with_ollama([{role: user, content: prompt}]) # 4. 整理返回结果 return { answer: answer, source_documents: retrieved_docs, is_rag: True }4.3 构建FastAPI主应用将上述服务整合到一个FastAPI应用中。# app/main.py from fastapi import FastAPI, UploadFile, File, HTTPException from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel import os import uuid from typing import Optional from app.services.document_processor import DocumentProcessor from app.services.vector_store import VectorStoreService from app.services.rag_service import RAGService # 初始化应用 app FastAPI(title本地RAG知识库问答系统, version1.0.0) # 添加CORS中间件方便前端调用 app.add_middleware( CORSMiddleware, allow_origins[*], # 生产环境应指定具体域名 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) # 初始化全局服务 vector_store VectorStoreService() rag_service RAGService(vector_store) doc_processor DocumentProcessor() # 定义请求/响应模型 class QuestionRequest(BaseModel): question: str use_rag: bool True class QuestionResponse(BaseModel): answer: str source_documents: list is_rag: bool request_id: str class UploadResponse(BaseModel): message: str file_id: str chunk_count: int # API端点健康检查 app.get(/) async def root(): return {message: RAG知识库问答系统已就绪, status: healthy} # API端点问答 app.post(/ask, response_modelQuestionResponse) async def ask_question(request: QuestionRequest): 接收用户问题返回RAG或直接生成的答案 try: result rag_service.answer_question(request.question, use_contextrequest.use_rag) result[request_id] str(uuid.uuid4()) return result except Exception as e: raise HTTPException(status_code500, detailf处理问题时出错: {str(e)}) # API端点上传文档如PDF并构建知识库 app.post(/upload, response_modelUploadResponse) async def upload_document(file: UploadFile File(...)): 上传文档文件解析并存入向量数据库 if not file.filename.endswith(.pdf): raise HTTPException(status_code400, detail仅支持PDF文件) # 保存上传的文件 file_id str(uuid.uuid4()) file_path f./uploads/{file_id}.pdf os.makedirs(./uploads, exist_okTrue) with open(file_path, wb) as f: content await file.read() f.write(content) try: # 处理PDF文件 chunks doc_processor.load_and_split_pdf(file_path) # 存入向量数据库 vector_store.add_documents(chunks, metadatas[{source: file.filename} for _ in chunks]) # 可选删除临时文件 os.remove(file_path) return UploadResponse( message文档上传并处理成功, file_idfile_id, chunk_countlen(chunks) ) except Exception as e: # 清理临时文件 if os.path.exists(file_path): os.remove(file_path) raise HTTPException(status_code500, detailf文档处理失败: {str(e)}) # API端点获取系统状态 app.get(/status) async def get_status(): 获取向量数据库状态 collection_info vector_store.collection.count() return { vector_db_document_count: collection_info, embedding_model: vector_store.embedding_model.__class__.__name__, status: running } if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)4.4 运行与测试应用启动Ollama服务如果使用Ollamaollama run qwen2.5:7b # 保持此终端运行启动FastAPI应用cd my-ai-app uvicorn app.main:app --reload --host 0.0.0.0 --port 8001测试API打开浏览器访问http://localhost:8001/docs可以看到自动生成的Swagger UI界面。首先通过/upload接口上传一个PDF文件。然后通过/ask接口提问设置use_rag为true。5. 容器化部署使用Docker封装应用为了确保应用在任何环境都能一致运行我们需要将其Docker化。5.1 编写Dockerfile# Dockerfile # 使用官方Python镜像作为基础 FROM python:3.10-slim # 设置工作目录 WORKDIR /app # 设置环境变量 ENV PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 \ PIP_NO_CACHE_DIR1 # 安装系统依赖例如如果需要编译某些Python包 RUN apt-get update apt-get install -y --no-install-recommends \ gcc \ g \ rm -rf /var/lib/apt/lists/* # 复制依赖文件并安装 COPY requirements.txt . RUN pip install --upgrade pip \ pip install -r requirements.txt # 复制应用代码 COPY app/ ./app/ COPY configs/ ./configs/ COPY scripts/ ./scripts/ # 创建非root用户运行应用安全最佳实践 RUN useradd -m -u 1000 appuser chown -R appuser:appuser /app USER appuser # 暴露端口FastAPI应用端口 EXPOSE 8001 # 健康检查 HEALTHCHECK --interval30s --timeout3s --start-period5s --retries3 \ CMD python -c import requests; requests.get(http://localhost:8001/) || exit 1 # 启动命令 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8001]5.2 编写docker-compose.yml多服务编排在实际场景中我们的应用可能依赖多个服务如向量数据库Chroma、缓存Redis等。使用Docker Compose可以轻松编排。# docker-compose.yml version: 3.8 services: # Ollama服务提供大模型能力 ollama: image: ollama/ollama:latest container_name: ai-app-ollama ports: - 11434:11434 volumes: - ollama_data:/root/.ollama # 在容器启动时自动拉取模型可选 # command: # sh -c ollama pull qwen2.5:7b ollama run qwen2.5:7b # 或者启动后手动拉取docker exec ai-app-ollama ollama pull qwen2.5:7b restart: unless-stopped # 向量数据库ChromaDB chromadb: image: chromadb/chroma:latest container_name: ai-app-chromadb ports: - 8002:8000 environment: - IS_PERSISTENTTRUE - PERSIST_DIRECTORY/chroma/data volumes: - chroma_data:/chroma/data restart: unless-stopped # 主应用服务 ai-app: build: . container_name: ai-app-backend ports: - 8001:8001 environment: - OLLAMA_BASE_URLhttp://ollama:11434 - CHROMA_SERVER_HOSTchromadb - CHROMA_SERVER_HTTP_PORT8000 volumes: - ./uploads:/app/uploads # 挂载上传目录持久化文件 depends_on: - ollama - chromadb restart: unless-stopped # 可选Nginx作为反向代理和负载均衡 nginx: image: nginx:alpine container_name: ai-app-nginx ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro depends_on: - ai-app restart: unless-stopped volumes: ollama_data: chroma_data:5.3 构建与运行# 1. 构建Docker镜像 docker-compose build # 2. 启动所有服务 docker-compose up -d # 3. 查看日志 docker-compose logs -f ai-app # 4. 停止服务 docker-compose down # 5. 停止并清理数据卷谨慎操作 # docker-compose down -v6. 生产环境部署与监控将容器化的应用部署到生产环境需要考虑更多因素高可用、负载均衡、监控、安全等。6.1 使用Nginx作为反向代理虽然Docker Compose中已经包含了Nginx但让我们看看一个基本的Nginx配置。# nginx.conf events { worker_connections 1024; } http { upstream ai_app_backend { # 负载均衡到多个后端实例如果做了水平扩展 server ai-app:8001; # server ai-app2:8001; # 另一个实例 } server { listen 80; server_name your-domain.com; # 替换为你的域名 # 静态文件服务如果有 location /static/ { alias /app/static/; expires 30d; } # API反向代理 location / { proxy_pass http://ai_app_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 超时设置对于LLM长文本生成很重要 proxy_connect_timeout 60s; proxy_send_timeout 300s; # 根据模型响应时间调整 proxy_read_timeout 300s; } # 健康检查端点 location /health { proxy_pass http://ai_app_backend/; access_log off; } } }6.2 集成Prometheus监控监控是生产环境的眼睛。我们可以为FastAPI应用添加Prometheus指标。安装依赖pip install prometheus-client在FastAPI应用中添加监控# app/monitoring.py from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST from fastapi import Response import time # 定义指标 REQUEST_COUNT Counter( http_requests_total, Total HTTP Requests, [method, endpoint, status] ) REQUEST_LATENCY Histogram( http_request_duration_seconds, HTTP request latency in seconds, [method, endpoint] ) # 中间件记录请求指标 app.middleware(http) async def monitor_requests(request, call_next): start_time time.time() method request.method endpoint request.url.path try: response await call_next(request) status_code response.status_code except Exception: status_code 500 raise finally: latency time.time() - start_time REQUEST_COUNT.labels(methodmethod, endpointendpoint, statusstatus_code).inc() REQUEST_LATENCY.labels(methodmethod, endpointendpoint).observe(latency) return response # 添加Prometheus指标端点 app.get(/metrics) async def metrics(): return Response(generate_latest(), media_typeCONTENT_TYPE_LATEST)配置Prometheus抓取# prometheus.yml global: scrape_interval: 15s scrape_configs: - job_name: ai-app static_configs: - targets: [ai-app:8001] # Docker服务名6.3 使用环境变量管理配置永远不要将敏感信息如API密钥、数据库密码硬编码在代码中。使用环境变量或配置文件。# app/config.py import os from dotenv import load_dotenv load_dotenv() # 从.env文件加载环境变量 class Config: # Ollama配置 OLLAMA_BASE_URL os.getenv(OLLAMA_BASE_URL, http://localhost:11434) OLLAMA_MODEL os.getenv(OLLAMA_MODEL, qwen2.5:7b) # 向量数据库配置 CHROMA_PERSIST_DIR os.getenv(CHROMA_PERSIST_DIR, ./chroma_db) EMBEDDING_MODEL os.getenv(EMBEDDING_MODEL, all-MiniLM-L6-v2) # 应用配置 UPLOAD_FOLDER os.getenv(UPLOAD_FOLDER, ./uploads) MAX_UPLOAD_SIZE int(os.getenv(MAX_UPLOAD_SIZE, 10 * 1024 * 1024)) # 10MB config Config()创建.env文件OLLAMA_BASE_URLhttp://ollama:11434 CHROMA_PERSIST_DIR/app/chroma_data EMBEDDING_MODELparaphrase-multilingual-MiniLM-L12-v2 MAX_UPLOAD_SIZE524288007. 常见问题与排查指南在构建和部署过程中你几乎一定会遇到以下问题。7.1 模型加载与推理问题问题现象可能原因解决方案CUDA out of memory模型太大GPU内存不足1. 使用更小的模型。2. 使用量化模型如GPTQ, GGUF。3. 使用device_mapauto和torch_dtypetorch.float16。4. 使用vLLM的PagedAttention。加载模型非常慢首次下载或网络问题1. 提前下载模型到本地使用本地路径加载。2. 使用国内镜像源。推理速度慢硬件性能不足或未使用GPU1. 确认torch.cuda.is_available()为True。2. 使用vLLM替代原生Transformers。3. 调整批处理大小。7.2 部署与网络问题问题现象可能原因解决方案容器内无法连接localhost服务Docker网络隔离使用服务名如http://ollama:11434而非localhost。端口已被占用端口冲突更改应用或Docker Compose中的端口映射。上传文件失败权限问题或路径不存在1. 确保Docker卷挂载正确。2. 检查应用对目录的读写权限。7.3 RAG效果不佳问题现象可能原因解决方案检索不到相关内容1. 文档切分不合理。2. 嵌入模型不匹配。3. 查询与文档语义不匹配。1. 调整chunk_size和chunk_overlap。2. 尝试不同的嵌入模型如bge-large-zh-v1.5。3. 对查询进行重写或扩展。答案与文档无关幻觉提示词设计不佳或模型未遵循指令1. 强化提示词明确要求“基于上下文”。2. 在提示词中要求模型引用来源。3. 使用更好的模型。8. 最佳实践与进阶建议8.1 开发阶段最佳实践版本固化使用requirements.txt或poetry精确管理所有依赖版本并在Dockerfile中固定基础镜像版本。配置分离将所有配置数据库连接、API密钥、模型路径通过环境变量管理区分开发、测试、生产环境。日志结构化使用structlog或json-logger输出结构化日志便于后续使用ELK或Loki收集分析。单元测试为关键业务逻辑如文档处理、向量检索编写单元测试确保核心功能稳定。8.2 部署与运维最佳实践健康检查为每个服务设置/health端点并在Docker和Kubernetes中配置存活和就绪探针。资源限制在Docker Compose或Kubernetes中为容器设置CPU和内存限制防止单个服务耗尽主机资源。滚动更新与回滚在生产环境使用Kubernetes的Deployment或Docker Swarm实现零停机更新和快速回滚。备份策略定期备份向量数据库的持久化数据如Chroma的chroma_data卷。8.3 性能与成本优化模型量化使用GGUF或GPTQ格式的量化模型可在几乎不损失精度的情况下大幅降低内存占用和提升推理速度。缓存层为频繁的相同查询引入Redis缓存存储(query, answer)对减少对LLM的调用。异步处理对于耗时的文档解析和向量化任务使用Celery或Dramatiq等异步任务队列避免阻塞HTTP请求。分级存储热数据使用内存或SSD存储冷数据归档到对象存储如S3、MinIO。8.4 安全考量输入验证与清理对所有用户输入特别是上传文件进行严格验证防止路径遍历、恶意文件上传等攻击。速率限制使用slowapi等库为API添加速率限制防止滥用。API密钥保护如果使用付费API如OpenAI确保密钥不泄露可使用Vault等密钥管理工具。网络隔离在生产环境将数据库、模型服务等后端组件置于内网仅通过API网关暴露必要端口。构建和部署AI应用是一个涉及多领域知识的系统工程从环境管理、模型服务化、应用开发到容器化部署和生产运维每一步都需要扎实的技能和细致的考量。本文以构建一个本地RAG问答系统为主线串联起了这些核心技能点并提供了可运行的代码示例。真正的掌握始于动手实践建议你从本地运行Ollama和FastAPI示例开始逐步加入向量数据库最后尝试用Docker Compose编排所有服务。在这个过程中你积累的不仅是代码更是应对复杂AI工程问题的系统性思维和实战经验。