0
0
0

零基础搭建本地AI编程代理实战与踩坑指南

优雅鹤
2026-06-07 02:58
阅读 596

大家好，我是技术团队的培训负责人。最近带新一届应届生的时候，发现大家对 AI 辅助编程特别感兴趣，但往往停留在“让 AI 写个正则”或者“解释一段代码”的初级阶段。为了让大家真正理解 AI 是如何“自主”写代码的，我带大家做了一次深度的技术探索。

为什么要写这篇教程？因为我当初学的时候，也是看着一堆高大上的名词发懵，踩了无数坑才摸清门道。很多新手在配置环境时卡了几天，或者被 AI 生成的错误代码带偏了方向。今天，我就把带团队探索 AI 编程代理（AI Coding Agent）的踩坑记录整理出来。我们将围绕三个核心关键词：JetBrains Junie、LM Studio 和 Hermes Agent，带大家从零开始，搞懂云端和本地 AI 代理到底怎么玩。

核心概念：用大白话解释 AI 代理

在动手之前，我们必须先搞清楚这三个名词到底是个啥。别被专业术语吓到，我用最通俗的语言给大家翻译一下：

  • JetBrains Junie：这是 JetBrains 官方推出的 AI 软件工程师。它不仅仅是个代码补全工具，它能理解整个项目的上下文，自主修改多个文件、运行测试，甚至自己修 Bug。你可以把它理解为 JetBrains 给你配的一个“云端初级程序员”，它住在 IDE 里，随叫随到。
  • LM Studio：一个让你在本地电脑上跑大语言模型的桌面软件。它的最大优势是完全本地化。不用联网，不用担心公司代码泄露，你的显卡就是它的算力。它提供了一个兼容 OpenAI 格式的本地 API，方便我们写代码去调用它。
  • Hermes Agent：Hermes 是 NousResearch 开源的一系列大模型，特别擅长“函数调用（Function Calling）”和“逻辑推理”。当我们把 Hermes 模型接入到自定义的代码逻辑中，让它能自主调用工具（比如读写文件、执行终端命令），这就成了一个 Hermes Agent（本地 AI 代理）。

简单来说，Junie 是官方做好的成品大餐，而 LM Studio + Hermes Agent 则是我们自己去菜市场买菜（本地模型）并亲自下厨（编写 Agent 逻辑）做出来的定制私房菜。

环境准备：工欲善其事，必先利其器

我当初学的时候，环境配置就搞了整整两天。为了让大家少走弯路，请严格按照以下步骤操作。

1. 搭建本地模型服务 (LM Studio)

  1. 前往 LM Studio 官网下载并安装客户端（支持 Windows/Mac/Linux）。
  2. 打开软件，在左侧导航栏点击放大镜图标（搜索模型）。
  3. 在搜索框输入 Hermes 3 Llama 3.1 8B。推荐下载 Q4_K_M 量化版本，它在性能和显存占用之间取得了最好的平衡。
  4. 下载完成后，点击左侧的“本地服务器（Local Server）”图标。
  5. 顶部选择刚才下载的 Hermes 模型，点击“启动服务器”。
  6. 关键参数设置：
    • GPU Offload：拉到最大（Max），让显卡全负荷工作。
    • Context Length：设置为 8192 或 16384（根据你的显存大小决定，显存小就设小点，防止 OOM）。
    • 看到控制台输出 Server started on http://localhost:1234 即表示成功。

2. 准备 JetBrains Junie

  1. 确保你的 IntelliJ IDEA 或 PyCharm 是 2024.3 或更新版本。
  2. 进入 Settings/Preferences -> Plugins，搜索并安装 JetBrains Junie 插件。
  3. 注意：Junie 目前仍处于早期访问阶段（Early Access Program），你可能需要在 JetBrains 官网申请加入等待名单。如果暂时没权限，可以先重点学习下面的本地 Agent 方案。

实战项目：两条路线的踩坑记录

接下来，我们分别用这两条路线完成一个实战任务：让 AI 自动读取本地的 requirements.txt 文件，并生成一份依赖说明文档 dependencies.md。

路线一：体验云端 AI 工程师 JetBrains Junie

在 IDEA 中打开 Junie 面板，输入指令：“请读取项目根目录下的 requirements.txt，解析里面的 Python 依赖，并生成一个 dependencies.md 文件，包含每个库的简单说明。”

踩坑记录与避坑指南

  1. 上下文丢失问题：Junie 有时候会“忘记”项目结构。
    • 解决：在 Prompt 中明确指定文件路径，例如“请读取 ./backend/requirements.txt”。
  2. 擅自修改不相关文件：Junie 在生成文档时，可能会“好心”帮你格式化一下代码文件。
    • 解决：在指令中加上严格限制：“仅允许创建 dependencies.md，严禁修改任何其他文件。”
  3. 执行卡死：如果项目很大，Junie 扫描索引会非常慢。
    • 解决：在 IDEA 设置中，将不需要 AI 关注的目录（如 node_modules, venv, .git）标记为 Excluded。

路线二：手搓本地 AI 代理 Hermes Agent

既然 Junie 有诸多限制，我们自己用 Python 写一个本地 Agent 行不行？当然行！我们将使用 Python 的 openai 库连接 LM Studio 的本地 API，利用 Hermes 模型的 Function Calling 能力来实现。

1. 编写 Agent 代码

请确保安装了依赖：pip install openai

import os
import json
from openai import OpenAI

# 1. 初始化客户端，指向 LM Studio 的本地地址
client = OpenAI(base_url="http://localhost:1234/v1", api_key="not-needed")

# 2. 定义 Agent 可以使用的工具（函数）
tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "读取本地指定路径的文件内容",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {
                        "type": "string",
                        "description": "文件的相对或绝对路径，例如 requirements.txt"
                    }
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "write_file",
            "description": "将内容写入本地指定路径的文件",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "目标文件路径"},
                    "content": {"type": "string", "description": "要写入的文件内容"}
                },
                "required": ["file_path", "content"]
            }
        }
    }
]

# 3. 实现工具的具体执行逻辑
def execute_function(name, arguments):
    args = json.loads(arguments)
    if name == "read_file":
        try:
            with open(args["file_path"], "r", encoding="utf-8") as f:
                return f.read()
        except Exception as e:
            return f"读取文件失败: {str(e)}"
    elif name == "write_file":
        try:
            with open(args["file_path"], "w", encoding="utf-8") as f:
                f.write(args["content"])
            return "文件写入成功"
        except Exception as e:
            return f"写入文件失败: {str(e)}"
    return "未知函数"

# 4. 核心 Agent 循环
def run_agent(user_prompt):
    messages = [{"role": "system", "content": "你是一个本地编程助手，请使用提供的工具完成任务。"},
                {"role": "user", "content": user_prompt}]

    while True:
        # 调用 LM Studio 本地模型
        response = client.chat.completions.create(
            model="hermes-3-llama-3.1-8b", # 需与 LM Studio 中加载的模型名称一致
            messages=messages,
            tools=tools,
            tool_choice="auto",
            temperature=0.1 # 降低温度，让输出更稳定
        )
        
        message = response.choices[0].message
        messages.append(message)

        # 如果模型决定调用工具
        if message.tool_calls:
            for tool_call in message.tool_calls:
                func_name = tool_call.function.name
                func_args = tool_call.function.arguments
                print(f"[Agent 思考] 调用工具: {func_name}, 参数: {func_args}")
                
                # 执行工具并获取结果
                result = execute_function(func_name, func_args)
                print(f"[工具返回] {result[:50]}...") # 截断打印
                
                # 将工具执行结果反馈给模型
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result
                })
        else:
            # 没有工具调用，说明任务完成，输出最终回答
            print("\n=== 最终回答 ===")
            print(message.content)
            break

if __name__ == "__main__":
    prompt = "请读取 requirements.txt，解析依赖，并生成 dependencies.md 说明文档。"
    run_agent(prompt)

2. Hermes Agent 踩坑记录

  1. Function Calling 格式解析失败：
    • 现象：Hermes 模型有时不返回标准的 JSON，而是返回带有 Markdown 代码块的 JSON（如 json {...}）。
    • 解决：在 execute_function 中加一个正则清洗，或者在 System Prompt 中严厉强调：“必须且只能返回纯 JSON，不要包含任何 Markdown 标记。”
  2. LM Studio 内存溢出 (OOM)：
    • 现象：当 requirements.txt 很大，或者生成的 dependencies.md 很长时，Context Length 爆满，LM Studio 直接崩溃。
    • 解决：在 LM Studio 中开启 Flash Attention（如果显卡支持），并适当调小 Context Length。在代码中，对读取的文件内容进行截断或分块处理。
  3. Agent 陷入死循环：
    • 现象：模型一直调用 read_file，不执行 write_file。
    • 解决：在 System Prompt 中加入步骤规划：“请先读取文件，分析内容，最后必须调用 write_file 保存结果。”同时，在代码中加一个最大循环次数限制（如 max_iterations = 5），防止死循环。

3. Hermes Agent 工作流程图

为了让大家更直观地理解 Agent 是怎么工作的，我画了一个简单的文字流程图：

[用户输入指令] 
      │
      ▼
[Agent 接收指令] ──> 结合 System Prompt 和 Tools 定义
      │
      ▼
[调用 LM Studio 本地 API] <───────────────┐
      │                                   │
      ▼                                   │
{模型判断：需要调用工具吗？}               │
      │                                   │
      ├─ 是 ──> [执行本地 Python 函数] ──> [将结果返回给模型] ─┘
      │         (如 read_file)            (作为 tool role 消息)
      │
      └─ 否 ──> [输出最终文本回答] ──> [任务结束]

常见问题：新手答疑时间

在带应届生的过程中，我收集了大家最容易遇到的几个问题，这里统一解答：

Q1：LM Studio 跑模型太卡，生成速度只有 2 tokens/s 怎么办？ A：这通常是显存没吃满或者内存带宽瓶颈。首先检查 LM Studio 的 GPU Offload 是否拉满。如果模型大小超过了你的显卡显存（比如 8B 模型 Q4 量化大约需要 6GB 显存，而你只有 4GB），系统会使用内存进行计算，速度会断崖式下跌。建议更换更小的量化版本（如 Q2/Q3），或者换用 3B/2B 级别的小模型（如 Hermes 2 Pro Llama 3 8B 可以换成 Qwen2.5 3B）。

Q2：Junie 生成的代码跑不通，一直报错死循环怎么破？ A：这是目前所有 AI 编程助手的通病。Junie 在遇到报错时，有时会盲目修改不相关的代码。 避坑指南：当 Junie 连续两次修复同一个 Bug 失败时，立刻停止它。手动介入，把完整的报错堆栈复制给它，并明确告诉它：“不要修改 XXX 文件，只关注 YYY 逻辑”。另外，一定要善用 Git，每次让 AI 大改前，先 git commit，随时准备回滚。

Q3：Hermes Agent 总是输出多余的废话，不返回标准 JSON 怎么办？ A：Hermes 模型虽然擅长 Function Calling，但它本质上还是个聊天模型。 解决：

  1. 调低 temperature 参数（建议 0.0 - 0.2）。
  2. 在 System Prompt 中使用 Few-Shot（少样本提示），给它一两个标准的输入输出示例。
  3. 如果还是不行，可以在代码层做兜底：用正则表达式提取大括号 {} 内的内容，再交给 json.loads() 解析。

学习建议与下一步路径

作为培训负责人，看到大家能跑通这些 Demo 我很高兴，但我想给你们一些更长远的建议：

  1. 不要迷信 AI，代码审查（Code Review）依然是核心。 AI 代理（无论是 Junie 还是 Hermes Agent）生成的代码，必须经过你的大脑审查。AI 会“幻觉”，会引入安全漏洞，会写出性能极差的嵌套循环。你是工程师，AI 只是你的高级打字机。

  2. 理解底层原理，不要只做“调包侠”。 今天我们用了 openai 库，但你要去理解底层的 HTTP 请求是怎么发的，Hermes 模型的 Chat Template 是怎么拼接的。只有懂了原理，当框架报错时你才知道怎么改。

  3. 下一步学习路径建议：

    • 进阶 Prompt 工程：学习如何使用 ReAct 框架、思维链（Chain of Thought）来优化 Agent 的推理能力。
    • 引入向量数据库：结合 ChromaDB 或 Milvus，给你的本地 Agent 加上 RAG（检索增强生成）能力，让它能读懂你们公司几万页的内部 Wiki。
    • 学习 LangChain / LlamaIndex：今天我们手搓了 Agent 逻辑，下一步可以学习这些成熟的框架，它们提供了更强大的工具链和记忆管理。

总结

从云端的 JetBrains Junie 到本地的 LM Studio + Hermes Agent，我们见证了 AI 编程从“辅助补全”向“自主代理”的跨越。踩坑是技术探索的必经之路，那些报错的日志、崩溃的显存，最终都会变成你技术简历上最宝贵的经验。

希望这篇踩坑记录能帮大家少走弯路。下次培训，我期待看到你们用这些工具做出更酷的项目。大家加油，遇到搞不定的 Bug，随时来工位找我！

标签:JetBrains JunieLM StudioHermes Agent

评论 0

最热最新
暂无评论

为你推荐

暂无相关推荐
优雅鹤Lv.1
0
影响力
0
文章
0
粉丝

相关推荐

暂无相关推荐

精选内容

暂无精选内容