适用场景
需要把「深度调研」这件事放在自己机器上的人：公司内部有大量文档、行业资料不适合直接丢给外部 API；或者你希望检索来源、抓取规则、引用核验标准完全自己说了算。LongCat-DeepResearch 这类开源深度调研智能体的工作方式是：先把问题拆成子问题 → 调用搜索与网页抓取 → 交叉比对多个来源 → 生成带引用的长报告。把模型、搜索后端、抓取服务都部署在本地，整条链路可以只从你指定的出口出网。
环境与前置条件
- 操作系统：Ubuntu 22.04 / 24.04 LTS，其他 Linux 发行版同理；Windows 建议走 WSL2
- Python：3.10 及以上，具体下限以官方文档当前版本为准
- 推理引擎：vLLM 或 SGLang 任一，需要能提供 OpenAI 兼容的
/v1/chat/completions - 显卡：全精度权重对显存要求较高，单卡 80GB 级别比较从容；显存有限时使用官方或社区提供的量化版本，实际占用以模型卡说明为准
- 内存：64GB 起步，检索与网页解析环节比较吃内存
- 磁盘：模型权重 + 网页缓存 + 报告产物，建议预留 300GB 以上 SSD
- Docker 与 docker compose：用来起 SearXNG 搜索后端
- 网络：能访问你要检索的站点；只做内网检索的场景可以不开放公网出口
分步骤部署
1. 建目录、拉代码
```bash
mkdir -p ~/deepresearch && cd ~/deepresearch
git clone <官方仓库地址> longcat-deepresearch
cd longcat-deepresearch
```
仓库地址、目录名、脚本入口都以官方仓库为准。拉下来之后能看到 README、推理脚本和示例配置，就算这步没问题。
2. 创建 Python 环境
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
```
如果仓库把「模型推理依赖」和「agent 依赖」拆成两个文件，按 README 的说明分别安装。装完自检一下：
```bash
python -c "import torch; print(torch.cuda.is_available())"
```
输出 True 说明 PyTorch 认到了显卡。
3. 下载模型权重
用 huggingface-cli 或 modelscope 把权重拉到本地目录：
```bash
pip install -U huggingface_hub
export HF_ENDPOINT=https://hf-mirror.com # 网络受限时可用镜像，以官方文档说明为准
huggingface-cli download <模型仓库名> --local-dir ./models/longcat-dr
```
模型名、是否使用量化版本，以官方模型卡当前说明为准。完成后 ./models/longcat-dr 下应出现 config.json、tokenizer 相关文件与权重分片。
4. 起推理服务（OpenAI 兼容）
```bash
python -m vllm.entrypoints.openai.api_server \
--model ./models/longcat-dr \
--served-model-name longcat-dr \
--host 0.0.0.0 --port 8000 \
--tensor-parallel-size 1 \
--max-model-len 32768 \
--gpu-memory-utilization 0.90
```
这一步把权重加载进显存并暴露 HTTP 接口。日志里出现 Uvicorn running on http://0.0.0.0:8000 即为启动成功。max-model-len 不要盲目调大，显存吃紧时优先降它。
5. 起自建搜索后端（SearXNG）
新建 searxng/docker-compose.yml：
```yaml
services:
searxng:
image: searxng/searxng:latest # tag 以官方文档当前推荐为准
ports:
- "8888:8080"
volumes:
- ./config:/etc/searxng
restart: unless-stopped
```
```bash
cd searxng && docker compose up -d
```
再改 searxng/config/settings.yml，确认两件事：search.formats 里包含 json，以及 server.secret_key 换成一个随机字符串。改完重启容器。
SearXNG 的作用是把多个搜索引擎的结果聚合成一个接口，agent 只跟你自己的搜索网关说话。检索源可控，也省掉了直接对接商业搜索 API 的麻烦。
6. 部署网页抓取服务
很多调研目标是 JS 渲染的页面，纯 HTTP 请求抓不到正文。用 Playwright 起一个无头浏览器：
```bash
pip install playwright
playwright install chromium
playwright install-deps chromium
```
如果仓库自带抓取服务（例如用 FastAPI 包一层 Playwright），按 README 启动即可；没有的话可以先只启用静态抓取，在配置里关掉动态渲染，后续再补：
```bash
python -m app.scraper_server --host 0.0.0.0 --port 8890
```
7. 配置 agent
```bash
cp configs/config.example.yaml configs/config.yaml
```
需要对齐的字段大致是这几类（字段名以仓库实际配置为准）：
```yaml
llm:
base_url: http://127.0.0.1:8000/v1
api_key: EMPTY
model: longcat-dr
temperature: 0.2
search:
provider: searxng
endpoint: http://127.0.0.1:8888/search
engines: [bing, duckduckgo, google]
top_k: 8
fetcher:
mode: browser # browser 或 http
endpoint: http://127.0.0.1:8890/fetch
timeout: 30
max_pages_per_task: 30
verifier:
enabled: true
min_sources_per_claim: 2 # 每条结论至少两个独立来源
output:
dir: ./reports
formats: [markdown, json]
```
verifier 这段是这类智能体和普通「搜索 + 总结」的分水岭：它会把报告里每条带引用的事实句拆出来，回到原始网页做比对，对不上的就标记为未核实。
8. 跑第一个任务
```bash
python -m longcat_deepresearch.run \
--config configs/config.yaml \
--question "国内新能源汽车充电桩的运营商格局近两年有哪些变化" \
--max-turns 12 \
--out reports/demo
```
--max-turns 是「规划—检索—阅读—再规划」的循环上限。调大能挖得更深，耗时和 token 消耗也按比例上涨，第一次先用小值试。
9. 引用核验与报告导出
跑完后 reports/demo/ 下通常会有：
report.md：带[1] [2]角标的正文citations.json：每条引用的 URL、抓取时间、原文片段trace.jsonl：每一轮的搜索词、打开的页面、中间结论
核验脚本一般随仓库提供：
```bash
python -m longcat_deepresearch.verify \
--report reports/demo/report.md \
--citations reports/demo/citations.json \
--out reports/demo/verify.json
```
输出里每条 claim 会带 supported / partial / unsupported 状态。需要 PDF 时本地用 pandoc 转：
```bash
pandoc reports/demo/report.md -o reports/demo/report.pdf --pdf-engine=xelatex
```
验证部署是否成功
按四层逐一验证：
```bash
1. 推理服务
curl -s http://127.0.0.1:8000/v1/models | head
期望：返回 JSON，data 数组里出现你配置的模型名
2. 搜索后端
curl -s "http://127.0.0.1:8888/search?q=test&format=json" | head -c 300
期望：返回 {"query": "test", "results": [...]}
3. 抓取服务
curl -s -X POST http://127.0.0.1:8890/fetch \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com"}' | head -c 300
期望：返回页面标题与正文文本
4. 端到端
ls reports/demo/
期望：report.md、citations.json、trace.jsonl 都存在，
且 report.md 里的角标编号能在 citations.json 中找到对应条目
```
判断报告质量有个土办法：随机挑三条带引用的结论，点开 citations.json 里的 URL，看原文是否真的支持这句话。三条都对得上，说明检索和核验链路是通的；有一条对不上，先去查 trace.jsonl 里那一条对应的抓取记录。
常见报错与解决
1. torch.cuda.OutOfMemoryError: CUDA out of memory
原因：显存不足，通常是上下文长度或显存利用率设得太大。
解决：降上下文、降并发，或换量化权重。
```bash
python -m vllm.entrypoints.openai.api_server \
--model ./models/longcat-dr --max-model-len 16384 \
--gpu-memory-utilization 0.85 --max-num-seqs 4
```
2. 搜索接口返回 403 或 format not supported
原因：SearXNG 默认不开放 JSON 输出，settings.yml 的 formats 里没加 json，或者 secret_key 还是默认值。
解决：改配置后重启容器。
```bash
grep -n "formats" -A3 searxng/config/settings.yml
docker compose -f searxng/docker-compose.yml restart
```
3. BrowserType.launch: Executable doesn't exist at ...
原因：只装了 Playwright 的 Python 包，没有下载浏览器二进制，或者缺系统依赖库。
解决：
```bash
playwright install chromium
playwright install-deps chromium
```
4. httpx.ConnectError: All connection attempts failed / Connection refused
原因：推理服务或抓取服务只监听了 127.0.0.1，而 agent 跑在容器里，容器内的 127.0.0.1 指向容器自身。
解决：服务端加 --host 0.0.0.0，配置里把地址改成宿主机 IP 或 compose 网络中的服务名。
5. 抓取一段时间后进程被 OOM Killer 杀掉
原因：并发抓取数过高，浏览器实例堆积。
解决：限制并发与单任务页数。
```yaml
fetcher:
concurrency: 2
max_pages_per_task: 20
```
同时在 systemd 或 compose 里给服务设内存上限，让它超限重启，而不是把整台机器拖垮。
6. 报告里引用编号对不上、出现「幻觉引用」
原因：长上下文里模型记错了来源编号，或者页面抓回来是空正文。
解决：打开 verifier 并提高 min_sources_per_claim；同时翻 trace.jsonl，把超时、403 的页面从引用来源里排除——抓取失败的页面不能充当证据。
后续维护
备份：需要备份的不是模型权重（可重新下载），而是 configs/、reports/、trace.jsonl 以及你的检索源白名单。写个定时任务打包到对象存储即可。
升级：推理引擎和 agent 仓库分开升级，一次只动一个。升级前把可用版本导出成锁文件（pip freeze > requirements.lock），出问题能回滚。模型权重与 agent 代码建议配套使用，具体对应关系以官方文档当前版本为准。
日志与监控：推理侧关注显存占用、请求排队时长、每秒输出 token 数；agent 侧关注每轮耗时、检索命中率、抓取失败率、核验通过率。核验通过率明显下降，通常是检索源质量变差或抓取被反爬拦截，而不是模型变笨了。容器日志用 docker compose logs -f --tail=200 查看，生产环境接一套 Prometheus + Grafana 更省心。
成本与安全：搜索后端和抓取服务不要直接暴露到公网，需要外部访问时前面加一层带鉴权的反向代理。给单次任务设 token 上限和最大轮数，避免一个失控任务把显卡占满一整天。网页缓存建议保留，同一 URL 短期内重复抓取既慢又容易触发封禁。