簡介這份實戰(zhàn)教程面向希望快速上手檢索增強生成系統(tǒng)的開發(fā)者與運維人員聚焦基于DeepSeek模型搭建RAG系統(tǒng)的完整環(huán)境部署流程。內(nèi)容從技術(shù)棧概要切入依次講解Dify服務(wù)器、Rerank與Embedding模型服務(wù)器、DeepSeek模型服務(wù)器的分步安裝部署并覆蓋CUDA驅(qū)動、vLLM推理庫、Docker容器化、xinference推理框架以及bge-reranker-large、bge-large-zh-v1.5等中文模型的落地配置幫助讀者打通從環(huán)境準備到模型驗證的關(guān)鍵環(huán)節(jié)。資源包為1個docx文檔約580KB目錄結(jié)構(gòu)清晰按技術(shù)棧概要與安裝部署兩大模塊組織便于對照查閱。目前已有326人學(xué)習(xí)適合需要系統(tǒng)掌握RAG環(huán)境搭建、排查部署細節(jié)的中高級開發(fā)者參考。1. 三臺機器、三個模型這套 RAG 環(huán)境為什么總在 CUDA 版本上翻車RAG 系統(tǒng)環(huán)境搭建這件事說簡單也簡單說坑也真坑。我見過太多人把 Dify、Xinference、vLLM 裝在同一臺機器上結(jié)果 CUDA 版本打架、Python 依賴沖突、顯存不夠最后連模型都加載不起來。這套基于 DeepSeek 的 RAG 系統(tǒng)核心思路是拆成三臺服務(wù)器各司其職ECS-1 跑 Dify 做應(yīng)用編排ECS-2 跑 Rerank 和 Embedding 模型做知識庫檢索ECS-3 跑 DeepSeek 大模型做推理生成。三臺機器環(huán)境不同、CUDA 版本不同、Python 版本也不同裝之前不把版本對齊后面全是玄學(xué)報錯。這篇筆記適合正在搭 RAG 環(huán)境、被 CUDA 和 vLLM 折磨過的開發(fā)者照著走能少踩幾個血淚坑。2. 裝之前先定版本三臺服務(wù)器的環(huán)境對照與選型邏輯2.1 三臺 ECS 的角色劃分與硬件要求這套 RAG 系統(tǒng)的部署架構(gòu)是典型的模型分離思路。Dify 作為應(yīng)用開發(fā)平臺負責(zé)流程編排、智能體創(chuàng)建和知識庫管理對顯卡沒什么要求用 Docker 部署就行。ECS-2 承擔(dān) Rerank 和 Embedding 兩個模型的推理選的是 NVIDIA Tesla T416GiB 顯存跑 bge-reranker-large 和 bge-large-zh-v1.5 這兩個模型剛好夠用。ECS-3 跑 DeepSeek-R1-Distill-Qwen-14B這個模型參數(shù)量大需要 Tesla V100 32GiB 顯存用 vLLM 做推理加速。為什么要把 Embedding 和 Rerank 放在同一臺機器因為這兩個模型在 RAG 流程里是前后腳調(diào)用的——先 Embedding 把知識庫文本向量化檢索時再用 Rerank 對候選結(jié)果重排序。放一起能減少網(wǎng)絡(luò)往返T4 的 16G 顯存同時加載這兩個模型也扛得住。DeepSeek 單獨放一臺是因為 14B 模型對顯存和算力要求高混部容易把 Embedding 服務(wù)擠爆。服務(wù)器角色鏡像顯卡PythonECS-1Dify 應(yīng)用平臺CentOS 7.5 64bit無要求Docker 內(nèi)置ECS-2Rerank EmbeddingUbuntu 20.04 Tesla Driver 470.223.02 CUDA 11.4T4 16GiB3.8ECS-3DeepSeek 推理CentOS 7.9 CUDA 11.4V100 32GiB3.102.2 版本選型的三個關(guān)鍵決策第一個決策是CUDA 版本。ECS-2 直接用鏡像自帶的 CUDA 11.4省事。ECS-3 雖然鏡像也是 CUDA 11.4但 vLLM 0.43 對 CUDA 12.1 支持更好所以需要手動升級驅(qū)動到 530.30.02再裝 CUDA 12.1。這里有個坑驅(qū)動和 CUDA 要分開裝一起裝會失敗。第二個決策是Python 版本。ECS-2 用 3.8因為 Xinference 在這個版本上最穩(wěn)。ECS-3 用 3.10vLLM 0.43 要求 Python 3.9 以上。兩個環(huán)境不要混用 conda 環(huán)境各管各的。第三個決策是模型精度。DeepSeek 啟動時用--dtype half半精度推理顯存占用減半效果損失很小。如果你的 V100 顯存緊張這個參數(shù)必加。提示裝之前先用nvidia-smi確認驅(qū)動版本用nvcc -V確認 CUDA 版本兩個版本號要能對上。驅(qū)動版本決定 CUDA 上限CUDA 版本決定 PyTorch 和 vLLM 能不能裝。3. 部署 ECS-2Xinference 安裝與 Rerank/Embedding 模型注冊3.1 Xinference 安裝與環(huán)境變量配置ECS-2 上要跑兩個模型用 Xinference 做推理框架。安裝命令很直接# 安裝 Xinference 完整版包含所有推理后端依賴 pip install xinference[all] # 配置模型存儲路徑避免默認路徑磁盤空間不足 export XINFERENCE_HOME/tmp/xinference # 驗證安裝是否成功 xinference --helpxinference[all]會裝一堆依賴包括 transformers、accelerate、sentence-transformers 等。如果磁盤空間緊張可以只裝需要的后端但 RAG 場景建議全裝省得后面缺庫。XINFERENCE_HOME指定模型緩存和配置文件的存放位置默認在用戶目錄下生產(chǎn)環(huán)境建議改到大盤。啟動 Xinference 有兩種方式# 前臺啟動調(diào)試時用能看到實時日志 xinference-local --host 0.0.0.0 --port 9997 # 后臺啟動生產(chǎn)環(huán)境用 nohup xinference-local --host 0.0.0.0 --port 9997 nohup.out 端口 9997 是 Xinference 的默認端口不要改因為后面 Dify 配置模型時要用這個端口。--host 0.0.0.0讓服務(wù)監(jiān)聽所有網(wǎng)卡否則 Dify 服務(wù)器訪問不到。3.2 注冊 bge-reranker-large 自定義模型Xinference 內(nèi)置了一些模型但 bge-reranker-large 需要手動注冊。先準備 config.json{ model_name: custom-bge-reranker-large, type: normal, language: [en, zh], model_id: BAAI/bge-reranker-large, model_uri: file:///path/to/bge-reranker-large }model_name是自定義名稱后面啟動模型時用這個名。model_uri指向本地模型文件路徑需要提前從 HuggingFace 下載好上傳到服務(wù)器。type填normal表示標準模型。注冊命令# 將自定義模型注冊到 Xinference xinference register --model-type rerank --file model.json --persist # 檢查注冊是否成功 xinference registrations --model-type rerank--persist參數(shù)讓注冊信息持久化重啟 Xinference 后不用重新注冊。注冊成功后用xinference launch啟動xinference launch --model-name custom-bge-reranker-large --model-type rerank如果需要注銷模型重新注冊用xinference unregister --model-type rerank --model-name custom-bge-reranker-large。3.3 注冊 bge-large-zh-v1.5 自定義模型Embedding 模型的注冊流程類似但 config.json 多了兩個關(guān)鍵參數(shù){ model_name: custom-bge-large-zh-v1.5, dimensions: 768, max_tokens: 512, language: [zh], model_id: BAAI/bge-large-zh-v1.5, model_uri: file:///path/to/bge-large-zh-v1.5 }dimensions是向量維度bge-large-zh-v1.5 輸出 768 維向量這個值必須和模型實際維度一致否則 Dify 那邊檢索會報維度不匹配。max_tokens是單次輸入最大 token 數(shù)512 是模型上限。注冊和啟動命令# 注冊 Embedding 模型 xinference register --model-type embedding --file model.json --persist # 檢查注冊結(jié)果 xinference registrations --model-type embedding # 啟動模型 xinference launch --model-name custom-bge-large-zh-v1.5 --model-type embedding兩個模型都啟動后Xinference 會在 9997 端口暴露 OpenAI 兼容的 API 接口。Dify 配置模型時填 ECS-2 的內(nèi)網(wǎng) IP 加 9997 端口就行。注意模型文件下載后要檢查完整性特別是 bin 文件和 config.json 是否齊全。我遇到過下載中斷導(dǎo)致模型加載失敗的情況重新下載后正常。4. 部署 ECS-3CUDA 12.1 升級、vLLM 安裝與 DeepSeek 啟動4.1 驅(qū)動與 CUDA 分開安裝的步驟ECS-3 的鏡像自帶 CUDA 11.4但 vLLM 0.43 需要 CUDA 12.1。升級過程分兩步先裝驅(qū)動再裝 CUDA一起裝會失敗。第一步安裝 NVIDIA 驅(qū)動 530.30.02# 下載驅(qū)動安裝包選擇 x86_64 架構(gòu)的歷史版本 530.30.02 # 安裝驅(qū)動過程中會提示禁用 nouveau 驅(qū)動 sh NVIDIA-Linux-x86_64-530.30.02.run第二步安裝 CUDA 12.1。驅(qū)動裝好后CUDA 安裝程序不會再嘗試裝驅(qū)動# 下載 CUDA 12.1 runfile sh cuda_12.1.0_530.30.02_linux.run --toolkit --silent --override--toolkit只裝 CUDA 工具包不裝驅(qū)動。--silent靜默安裝--override跳過編譯器版本檢查。第三步配置環(huán)境變量# 編輯 ~/.bashrc在末尾添加 export PATH/usr/local/cuda-12.1/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH # 刷新環(huán)境變量 source ~/.bashrc # 驗證 CUDA 版本 nvcc -Vnvcc -V輸出應(yīng)該是 CUDA 12.1。再用nvidia-smi看驅(qū)動版本右上角顯示的 CUDA 版本是驅(qū)動支持的最高版本只要不低于 12.1 就行。4.2 Python 3.10 環(huán)境與 PyTorch 依賴安裝用 conda 創(chuàng)建獨立環(huán)境# 創(chuàng)建 Python 3.10 虛擬環(huán)境 conda create -n myenv python3.10 -y # 激活環(huán)境 conda activate myenv安裝 PyTorch 時要注意版本匹配。vLLM 0.43 對 torch 版本有要求直接裝最新版會報錯# 安裝指定版本的 PyTorch匹配 CUDA 12.1 pip install torch2.3.0 torchvision0.18.0 torchaudio2.3.0 --index-url https://download.pytorch.org/whl/cu121--index-url指定 PyTorch 官方 CUDA 12.1 的 wheel 源。如果網(wǎng)絡(luò)慢可以換成國內(nèi)鏡像源但要注意鏡像源同步是否及時。4.3 vLLM 0.43 安裝與 DeepSeek 模型啟動安裝 vLLMpip install vllm0.43安裝過程中會出現(xiàn)依賴版本沖突的報錯比如 pydantic、fastapi 版本不匹配。按照報錯提示逐個安裝指定版本不要強行忽略。常見的是pip install pydantic1.10.13這類命令。模型文件提前下載好上傳到服務(wù)器路徑假設(shè)為/root/work/ds/pretrained。啟動命令python -m vllm.entrypoints.openai.api_server \ --model /root/work/ds/pretrained \ --dtype half \ --trust-remote-code \ --tensor-parallel-size 1 \ --max-model-len 5120 \ --enforce-eager \ --gpu-memory-utilization 0.95 \ --max-num-batched-tokens 5120 \ --max-num-seqs 5 \ --host 0.0.0.0 \ --served-model-name DeepSeek-R1-14B \ --port 8008 參數(shù)逐個說明--dtype half半精度推理顯存占用減半V100 上效果損失很小。--trust-remote-codeDeepSeek 模型有自定義代碼必須加這個參數(shù)。--tensor-parallel-size 1單卡推理如果是多卡可以改成卡數(shù)。--max-model-len 5120最大上下文長度根據(jù)顯存調(diào)整V100 32G 跑 5120 比較穩(wěn)。--enforce-eager禁用 CUDA graph避免某些環(huán)境下的兼容性問題。--gpu-memory-utilization 0.95GPU 顯存利用率0.95 表示用 95% 顯存。--max-num-batched-tokens 5120單批次最大 token 數(shù)和 max-model-len 保持一致。--max-num-seqs 5最大并發(fā)序列數(shù)顯存緊張就調(diào)小。--served-model-name DeepSeek-R1-14BAPI 調(diào)用時的模型名稱。--port 8008服務(wù)端口Dify 配置時填這個。啟動后用curl http://localhost:8008/v1/models檢查模型是否加載成功。5. 避坑記錄CUDA、依賴和顯存最容易翻車的五個地方5.1 nvcc 和 nvidia-smi 版本不一致現(xiàn)象nvcc -V顯示 CUDA 11.4nvidia-smi顯示 CUDA 12.1PyTorch 裝完提示 CUDA 不可用。原因驅(qū)動和 CUDA 工具包版本不匹配。nvidia-smi顯示的是驅(qū)動支持的最高 CUDA 版本nvcc -V顯示的是當(dāng)前工具包版本。兩者不一致時PyTorch 編譯時用的 CUDA 版本可能和運行時不一致。解決確保nvcc -V的版本和 PyTorch 安裝時指定的 CUDA 版本一致。如果驅(qū)動版本夠高可以裝多個 CUDA 工具包用環(huán)境變量切換。5.2 vLLM 安裝時依賴沖突現(xiàn)象pip install vllm0.43報錯提示 pydantic、fastapi、uvicorn 等包版本不兼容。原因vLLM 對依賴版本要求嚴格現(xiàn)有環(huán)境里的包版本不滿足要求。解決按照報錯提示逐個安裝指定版本。常見的是pip install pydantic1.10.13、pip install fastapi0.111.0。如果沖突太多建議新建干凈的 conda 環(huán)境重裝。5.3 模型加載時顯存不足現(xiàn)象vLLM 啟動時報CUDA out of memory或者 Xinference 加載模型時卡住。原因模型太大顯存不夠。DeepSeek 14B 半精度需要約 28G 顯存V100 32G 剛好夠但如果--gpu-memory-utilization設(shè)太高留給 KV cache 的顯存就不夠了。解決降低--gpu-memory-utilization到 0.85或者減小--max-model-len。如果還是不夠考慮量化模型。5.4 Xinference 注冊模型后啟動失敗現(xiàn)象xinference launch報錯提示模型文件不存在或 config.json 格式錯誤。原因model_uri路徑寫錯或者模型文件下載不完整。解決檢查model_uri指向的目錄下是否有config.json、pytorch_model.bin等文件。用ls -lh看文件大小是否正常bge-large-zh-v1.5 大約 1.3G。5.5 Dify 連接模型服務(wù)超時現(xiàn)象Dify 配置模型后測試連接一直轉(zhuǎn)圈最后提示超時。原因ECS-2 或 ECS-3 的安全組沒開放對應(yīng)端口或者 Xinference/vLLM 監(jiān)聽地址不是0.0.0.0。解決檢查安全組規(guī)則確保 9997 和 8008 端口對 Dify 服務(wù)器開放。檢查啟動命令里的--host參數(shù)是否為0.0.0.0。6. 裝完怎么驗證從模型加載到 RAG 全鏈路跑通環(huán)境裝完只是第一步能不能跑通才是關(guān)鍵。我一般按這個順序驗證第一步驗證 Xinference 服務(wù)。在 ECS-2 上執(zhí)行# 查看已注冊模型列表 xinference registrations --model-type rerank xinference registrations --model-type embedding # 查看正在運行的模型 xinference listxinference list會顯示模型名稱、類型、狀態(tài)和 API 地址。狀態(tài)是RUNNING才算正常。第二步驗證 vLLM 服務(wù)。在 ECS-3 上執(zhí)行# 檢查模型是否加載 curl http://localhost:8008/v1/models # 測試推理接口 curl http://localhost:8008/v1/completions \ -H Content-Type: application/json \ -d {model: DeepSeek-R1-14B, prompt: 你好, max_tokens: 10}如果返回 JSON 格式的推理結(jié)果說明 vLLM 正常。第三步驗證 Dify 連接。在 Dify 后臺的模型供應(yīng)商設(shè)置里分別添加 Xinference 和 vLLM 的 API 地址。Xinference 填http://ECS-2內(nèi)網(wǎng)IP:9997vLLM 填http://ECS-3內(nèi)網(wǎng)IP:8008/v1。添加后點測試連接顯示綠色對勾才算通。第四步跑一個完整的 RAG 流程。在 Dify 里創(chuàng)建一個知識庫上傳一個測試文檔然后創(chuàng)建一個聊天助手應(yīng)用關(guān)聯(lián)這個知識庫。提問一個文檔里有的問題看能不能檢索到相關(guān)內(nèi)容并生成回答。驗證項命令/操作預(yù)期結(jié)果Xinference 模型xinference list兩個模型狀態(tài) RUNNINGvLLM 模型curl /v1/models返回 DeepSeek-R1-14BDify 連接后臺測試連接綠色對勾RAG 全鏈路知識庫問答返回相關(guān)內(nèi)容這套驗證流程走完基本能確認環(huán)境沒問題。如果哪一步卡住回到對應(yīng)的避坑章節(jié)排查。從那以后我每次裝完環(huán)境都會先跑一遍這個驗證清單確認每個服務(wù)都正常再往下走。希望幫到你。本文還有配套的精品資源點擊獲取