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