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
)
