github鏈接：https://github.com/jd-opensource/joyagent-jdgenie
本篇博客記錄下自己在配置joyagent的過程，以【手動初始化環境，啟動服務】為例，后端調用的deepseek-chat大模型。
前言
JoyAgent是由京東云開源的企業級多智能體系統，具有以下顯著特點：
- 開箱即用的輕量級解決方案：JoyAgent無需依賴任何平臺，支持本地部署，安裝過程簡便，通過簡單的命令即可完成環境檢查和啟動服務。
- 高效的任務執行能力：在測試中，JoyAgent能夠在4-5分鐘內完成復雜任務，如美食店推薦和旅行規劃，且結果質量高，符合用戶需求。
- 優秀的交互體驗：JoyAgent提供清晰的工作空間界面，支持實時查詢和動態生成Markdown文檔，并提供多種結果保存方式（Joyspace轉換、MD文件下載、復制功能）。
- 企業級適用性：JoyAgent在京東內部已有超過2萬個智能體應用案例，覆蓋零售、物流、金融等多個領域，其GAIA基準測試準確率達70%以上，超越多個同類產品。
- 開源生態優勢：JoyAgent采用MIT協議，允許商業用途的二次開發，為企業和開發者提供了高度靈活的定制空間。
?實際測試使用中，于開發者需明確如下內容：
- 部署：可本地化部署
- 大模型：建議調用在線大模型，速度快效果好
- 功能：該平臺主要為智能體的搭建做服務
- 二次開發：開源的可完成日常工作的問題解答。若需接入公司系統中，完成指定的公司業務，需要進行二次開發
- 開發語言：以java為主、python為輔
1 環境準備：
- jdk17
sudo apt update sudo apt install openjdk-17-jdk # 驗證 java -version # 應該能看到 openjdk version "17.x"- python3.11 以及 python環境準備
conda create -n joy python=3.11 -c conda-forge conda activate joy pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simplecd genie-tool uv sync source .venv/bin/activate
2 工程配置
2.1 工程下載
git clone https://github.com/jd-opensource/joyagent-jdgenie.git
2.2 配置文件的修改
【1】文件： joyagent-jdgenie/genie-backend/src/main/resources/application.yml
將下面的第一段內容刪掉（注意是刪掉），替換成第二段內容。第二段內容是deepseek的相關配置
llm:default:base_url: '<input llm server here>'apikey: '<input llm key here>'interface_url: '/chat/completions'model: gpt-4.1max_tokens: 16384settings: '{"claude-3-7-sonnet-v1": {"model": "claude-3-7-sonnet-v1","max_tokens": 8192,"temperature": 0,"base_url": "<input llm server here>","apikey": "<input llm key here>","interface_url": "/chat/completions","max_input_tokens": 128000}}'llm:default:base_url: https://api.deepseek.comapikey: sk-*****model: deepseek-chatmax_tokens: 8192將文件內的 【
model_name: gpt-4.1】修改為【model_name: deepseek-chat】
?【2】文件： joyagent-jdgenie/genie-tool/.env_template
將 .env_template 文件復制一份 命名為 .env，修改 .env中內容
- 刪除
OPENAI_API_KEY=<your api key> OPENAI_BASE_URL=<your base url>- 補充和修改信息
DEEPSEEK_API_KEY=sk-*** DEFAULT_MODEL=deepseek/deepseek-chat SERPER_SEARCH_API_KEY=***
3 apikey 的獲取
3.1 deepseek的apikey
- deepseek官網 注冊并登錄賬號（支持手機號或微信掃碼）。
登錄后進入左側菜單的「API Keys」頁面，點擊「創建 API Key」。
填寫名稱并立即生成，密鑰只顯示一次，需妥善保存。- 使用的話需要充值，apikey才能真正有效
- 充值結束后，終端測試deepseek大模型是否能正常調通
curl -s https://api.deepseek.com/v1/chat/completions \-H "Content-Type: application/json" \-H "Authorization: Bearer sk-***" \-d '{"model": "deepseek-chat","messages": [{"role": "user", "content": "你好？"}],"max_tokens": 512,"temperature": 0.7}'
3.2 serper的apikey
這里前面申請過，然后谷歌郵箱忘記了，所以就先簡單記錄，后續有機會再詳細補充
- 打開 https://serper.dev。
- 點擊右上角 Sign Up。
- 使用 Gmail 郵箱填寫注冊信息并驗證。
- 登錄后進入 API Keys 頁面創建密鑰。
4 工程啟動
- 依賴與端口的測查
該條命令會檢查所有依賴和端口占用情況，根據提示直至不報錯即可。sh check_dep_port.sh # 檢查所有依賴和端口占用情況
- 一鍵式服務啟動
sh Genie_start.sh- 在 web中訪問 http://localhost:3000，正常情況下會出現如下界面
鍵入你好，會得到如下內容
詢問黃金價格波動影響因素
到此，該工程部署完成，且能夠正常使用。
5 部署過程中遇到的問題
5.1 一般庫的缺失
直接命令安裝即可
5.2：啟動時的warning
如下warning可以忽略，也可以安裝對應的庫解決
npm install esbuild@^0.17.0 prop-types@^15.5.9 --save-dev5.3 前端不停轉圈圈
本人實際場景：vscode遠程連接服務器部署與啟動，自動端口透傳到本地，也就是可以使用本地web界面直接訪問前端。
經過踩坑，確定排查方式如下：
- 確定服務啟動時，每個服務都是被正常拉起。若端口被占用，清除對應的端口的服務，然后重新運行，直至正確
- 確定端口透傳正確，保證不同端的服務在通信時，能夠調用正確的端口號。
在vscode下面終端界面中，點擊【PORTS】，保證里面的 【PORT】和【Forwarded Address】的端口號是相同的。
舉個例子。若將這里的【PORT】透傳到【localhost:4040】,我們在遠程服務器上curl -I http://localhost:3000是成功的，但在本地就會失敗。同時在web界面，localhost:4040 才能正常打開前端界面。
5.4 前端一直返回 “失敗，請聯系管理員”
當確保上面的異常都排除完后，出現【“任務執行失敗，請聯系管理員”】，這個時候就要排查 MCP客戶端是否能正常被調用。
- 確定deepseek的apikey是有效的，方法在前面講述過
- 配置文件 application.yml 中的 base_url: https://api.deepseek.com
注意這里不能寫成 base_url: https://api.deepseek.com/v1
本人在這里也踩了坑，后面通過日志打印，定位到這里了llm:default:base_url: https://api.deepseek.comapikey: sk-*****model: deepseek-chatmax_tokens: 8192
)
