用 4B 小模型做Code Agent的SubAgent？这个开源项目做到了

本地运行、零 API 成本、结构化输出 100% 准确 —— LocoOperator-4B 是一个专为代码库探索设计的蒸馏模型，或许会改变你使用 AI 辅助编程的方式。

背景：Code Agent的"贵"从哪来？

Code Agent 是目前最受开发者欢迎的Vibe Coding方式，很多Code Agent核心工作模式是主智能体 + 子智能体的两层架构：主模型负责决策和代码生成，子智能体负责在代码库里找文件、搜关键词、理清结构。

问题在于，子智能体做的大多是"体力活"——读文件、执行 grep、遍历目录——这些任务并不需要顶级大模型来完成，但每次调用都在消耗 API 额度。

LocoOperator-4B 的思路很简单：用一个本地 4B 小模型专门干这件事，把子智能体的 API 费用降到零。

什么是 LocoOperator-4B？

LocoOperator-4B 是由 LocoreMind 团队开发的开源模型，核心参数如下：

简单说：用 Qwen3-Coder-Next 的推理轨迹作为"答案"，教会了一个 4B 小模型模仿大模型在代码库探索任务上的行为。

它能干什么？

LocoOperator-4B 专注于工具调用型代码探索，支持以下七类工具：

• Read — 读取文件内容
• Grep — 在代码库中搜索字符串/正则
• Glob — 按模式匹配文件路径
• Bash — 执行只读 shell 命令（ls、find、cat 等）
• Write — 写入文件（辅助场景）
• Edit — 修改文件（辅助场景）
• Task — 发起子智能体委托

它生成的工具调用格式是结构化的 <tool_call> JSON，可以被 大部分Code Agent风格的智能体循环直接消费。

性能表现：小模型超越大模型的地方

测试集包含 65 个多轮对话样本，来源涵盖 scipy、fastapi、arrow、attrs、gevent、gunicorn 等主流开源项目，标注答案由 Qwen3-Coder-Next 生成。

核心指标

与教师模型的对比

这个结果有点反直觉：4B 的学生模型在结构化输出上超过了教它的大模型。 教师模型有 11 次工具调用出现了空参数（arguments: {}），而 LocoOperator-4B 全部正确。

这说明通过蒸馏，小模型有时候能学到比教师更"规整"的行为模式。

系统架构：如何接入 Claude Code

以Claude Code为例，介绍LocoOperator-4B如何接入Code Agent

LocoOperator-4B 的标准使用方式是接入一个两层智能体系统：

claude -p (sonnet 主模型)
  └─ 子智能体 (haiku) → 代理路由 → 本地 llama.cpp (LocoOperator-4B)

具体路由逻辑由一个代理脚本（scripts/proxy.py）控制：

• 主模型（Sonnet）通过 OpenRouter 运行，负责高层决策
• 子智能体（haiku）请求被代理拦截，转发给本地 4B 模型
• 如果本地模型遇到 context 溢出或超过 10 轮，自动回退到 OpenRouter

这套架构的优势在于对现有工作流零侵入——Claude Code 感知不到底层模型的切换。

快速上手

前置依赖

npm install -g @anthropic-ai/claude-code   # Claude Code
brew install llama.cpp                      # 本地推理（macOS）
curl -LsSf https://astral.sh/uv/install.sh | sh  # Python 包管理

启动本地模型服务

下载 GGUF 模型后，用 llama.cpp 起服务：

./llama-server \
    -m LocoOperator-4B.gguf \
    --ctx-size 51200 \
    --host 0.0.0.0 \
    --port 8080

推荐参数配置：

单条查询测试

./scripts/test_single.sh tqdm "How does tqdm detect if running in a Jupyter notebook?"

批量分析

./scripts/analyze.sh tqdm

结果保存至 data/outputs/tqdm/。

用 Python 直接调用（ModelScope）

from modelscope import AutoModelForCausalLM, AutoTokenizer
model_name = "LocoreMind/LocoOperator-4B"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)
messages = [
    {
        "role": "system",
        "content": "You are a read-only codebase search specialist. ..."
    },
    {
        "role": "user",
        "content": "Analyze the Black codebase at `/path/to/black`. How does it discover config files?"
    }
]
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer([text], return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=512)
print(tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))

最佳实践

1. System Prompt 要明确约束

LocoOperator-4B 被训练为只读探索智能体，System Prompt 里务必写清楚：只允许读操作，不允许写文件或执行状态变更命令。这能避免模型在模糊场景下误用 Bash 执行写操作。

CRITICAL CONSTRAINTS:
1. STRICTLY READ-ONLY: Only use tools for reading (ls, find, cat, grep).
2. Always use absolute file paths.

2. 上下文给够，轮次别太长

模型训练数据覆盖 3–33 轮对话，建议把最大轮次控制在 10 轮内，上下文窗口开到 50K，给工具输出留充足空间。

3. 利用代理的自动回退

对于特别复杂的探索任务（大型 monorepo、深度依赖链分析），本地模型可能遇到 context 限制。配置好代理的回退逻辑，让它在必要时自动切换到云端模型，不影响整体流程。

4. 评估工具选择差异而非结果正确性

首次工具类型匹配率只有 65.6%，但这不代表模型"答错了"——很多时候 Bash+grep 和直接用 Grep 工具都能找到同样的答案。评估时关注最终探索结果是否准确，而不是纠结工具选择是否和教师模型一致。

5. 批量任务预先准备查询文件

分析整个项目时，把所有查询整理成 tab 分隔的 id\tquery 格式存入 data/queries/ 目录，然后用 analyze.sh 批量执行。这比逐条手动测试效率高很多，结果也更容易对比。

已知局限

坦白讲，LocoOperator-4B 并非完美，团队也在 README 里列出了几个问题：

• 首次工具类型匹配率 65.6%，偏低 —— 有时候选择了不同但未必更差的工具
• 生成的工具调用总量少于教师模型（76 vs 89），并行调用能力偏弱
• 偏爱用 Bash 代替 Read，可能意味着它更依赖 shell 命令而非原生文件读取
• 测试集只有 65 个样本，规模偏小，泛化性还需验证

资源链接

模型权重（BF16）：https://modelscope.cn/models/LocoreMind/LocoOperator-4B

GGUF 量化版本：https://huggingface.co/LocoreMind/LocoOperator-4B-GGUF

完整代码与分析流水线：https://github.com/LocoreMind/LocoOperator

技术博客：https://locoremind.com/blog/loco-operator

LocoOperator-4B 是一个思路清晰的工程实验：不追求做全能模型，而是在一个具体场景（代码库探索）里把小模型的潜力压榨到极致。随着本地推理硬件越来越普及，这类"专用小模型 + 云端大模型"的混合架构，或许会成为 AI 编程工具的主流形态之一。

点击即可跳转模型链接：

https://modelscope.cn/models/LocoreMind/LocoOperator-4B