1. 项目概述为什么我们需要一个本地编程助手最近在折腾一个个人项目需要频繁地在不同编程语言和框架之间切换查文档、写示例代码、调试错误一套流程下来感觉时间都花在了“找”和“试”上而不是真正的“思考”和“创造”。相信很多开发者都有同感我们的大脑CPU不应该被搜索引擎的加载速度和API文档的跳转所占据。市面上的云端AI编程助手固然强大但涉及到公司代码、私有协议或者对网络延迟敏感的场景时总感觉束手束脚数据安全和响应速度都是问题。于是一个想法冒了出来能不能自己动手打造一个完全运行在本地的AI编程助手它不依赖任何外部API能理解我的自然语言指令调用本地工具比如代码解释器、文件系统、Git命令来完成任务并且整个思考过程对我透明。这不就是AI Agent的典型场景吗而实现它的核心技术正是当前大模型应用开发中的两个热门范式ReActReasoning Acting和Function Calling函数调用。这个项目就是一次将这两个概念落地的实战。我们将基于一个可以在本地部署的大语言模型LLM构建一个具备自主推理和行动能力的智能体Agent。它不仅能和你对话更能根据你的指令规划步骤、调用我们预先定义好的工具函数比如“写一个Python函数”、“在指定文件末尾添加代码”、“运行这段Shell命令并返回结果”并循环这个过程直到任务完成。最终你会得到一个完全受你控制、能力可无限扩展的“编程副驾驶”。接下来我将详细拆解从零到一构建这个本地助手的全过程包括核心原理、工具链选型、每一步的实操代码以及我踩过的那些坑。2. 核心架构与工具链选型构建一个AI Agent尤其是本地化的选型是第一步它直接决定了项目的可行性、性能和开发体验。我们需要一个清晰的架构并为其挑选合适的“零部件”。2.1 整体架构设计我们的本地编程助手核心是一个智能体循环。它的工作流程可以抽象为以下几步接收指令用户提出一个自然语言请求例如“在./src/utils.py文件里帮我写一个计算斐波那契数列的函数并添加对应的类型注解和文档字符串。”模型推理Reason本地大模型分析指令理解用户的意图并规划出下一步需要执行的动作Action。例如它可能推理出“用户需要我写代码。我应该先检查目标文件是否存在然后生成符合要求的函数代码最后将代码写入文件。”执行动作Act模型根据规划决定调用哪个工具Tool并生成调用该工具所需的参数。例如调用write_to_file工具参数为file_path“./src/utils.py”和content生成的代码。观察结果Observe工具执行后将结果成功或失败附带输出信息返回给模型。循环判断模型根据观察到的结果判断任务是否完成。如果未完成例如文件不存在需要先创建则回到第2步进行下一轮的推理和行动直到任务完成为止。这个“推理Reason- 行动Act- 观察Observe”的循环就是ReAct框架的核心思想。而Function Calling则是实现“行动Act”环节的关键技术它让大模型能够以结构化的方式调用我们预先定义好的函数。2.2 核心组件选型解析1. 大语言模型LLM本地运行的“大脑”这是Agent的智能核心。选择本地模型主要考虑三点性能足够强、支持Function Calling、硬件资源友好。为什么不是ChatGPT/Claude它们虽然功能强大但需要网络和API密钥无法满足“完全本地、数据不出境”的核心需求。备选模型Qwen2.5-7B-Instruct、Llama 3.1-8B-Instruct、DeepSeek-Coder-V2-Lite。这些模型在代码能力、指令跟随和工具调用方面表现不错且参数量在7B-16B之间在消费级显卡如RTX 4060 16GB上可以流畅运行。最终选择我选择了Qwen2.5-7B-Instruct。原因如下首先它的工具调用Function Calling能力经过专门优化格式规范响应稳定。其次7B的参数量对硬件要求相对友好通过量化技术如GPTQ、AWQ可以在8GB显存上运行。最后它的中英文代码和理解能力比较均衡适合我的使用场景。注意事项务必下载带有-Instruct后缀的版本这是经过对话和指令微调的对于理解用户意图和遵循ReAct格式至关重要。原始预训练模型Base Model通常不具备这么好的指令跟随能力。2. 模型推理框架如何高效运行模型我们需要一个库来加载模型、处理对话、并管理生成过程。为什么不是直接调用transformers虽然可以但我们需要自己处理聊天模板、历史记录、停止词等比较繁琐。主流选择vLLM追求极致吞吐、llama.cpp追求极致轻量和CPU推理、Ollama开箱即用的管理工具、LM Studio图形化界面。最终选择我使用Ollama作为本地模型服务。它极其简单一条命令就能拉取和运行模型并且内置了OpenAI兼容的API接口http://localhost:11434/v1这让我们后续可以使用标准的OpenAI SDK来调用它大大简化了开发。命令很简单ollama run qwen2.5:7b-instruct。对于更注重控制和生产环境我会用vLLM部署但Ollama在原型开发和个人使用中体验最佳。3. Agent开发框架实现ReAct循环的“脚手架”手动实现ReAct循环、工具管理、历史追踪是个复杂工程。使用成熟的Agent框架可以事半功倍。为什么需要框架它们封装了Agent的核心循环、工具调用、记忆管理等通用逻辑我们只需关注定义工具和任务本身。主流选择LangChain/LangGraph生态强大但稍显臃肿、LlamaIndex擅长与数据结合、Microsoft Autogen多Agent协作、CrewAI面向工作流。最终选择我选择了LangChain。虽然它被诟病“抽象泄漏”你需要了解其底层但其社区活跃、文档丰富、工具集成度最高。对于这个项目我们主要使用它的Agent、Tools和OpenAI兼容模块。它的create_react_agent函数能直接帮我们构建一个标准的ReAct Agent。4. 工具Tools定义Agent的“手和脚”这是赋予Agent能力的关键。我们将用Python函数来定义工具并用装饰器告诉LangChain这些是可被调用的工具。核心工具规划execute_shell_command: 执行Shell命令并返回输出用于运行脚本、Git操作等。read_file: 读取指定文件的内容。write_to_file: 向指定文件写入内容覆盖或追加。list_directory: 列出指定目录下的文件和文件夹。python_repl: 一个安全的Python交互式环境用于执行代码片段并返回结果这是代码助手的核心。安全警告execute_shell_command和python_repl是高风险工具必须施加严格的沙箱或权限限制。在个人开发环境中我们基于信任但仍建议避免赋予其删除根目录、格式化磁盘等危险操作的权限。在生产环境中必须使用 Docker 容器、资源限制和命令白名单等机制进行隔离。3. 环境搭建与基础工具实现理论清晰后我们开始动手。首先确保你的开发环境已经就绪。3.1 本地模型服务部署安装Ollama访问Ollama官网根据你的操作系统Windows/macOS/Linux下载并安装。拉取并运行模型打开终端执行以下命令。这会自动下载模型并启动一个本地API服务。ollama run qwen2.5:7b-instruct首次运行需要下载约4.5GB的模型文件。运行成功后终端会保持运行状态API服务在http://localhost:11434就绪。验证API打开另一个终端用curl测试一下。curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b-instruct, messages: [{role: user, content: Hello, write a simple Python function to add two numbers.}], stream: false }如果看到返回一个包含AI回复的JSON说明模型服务运行正常。3.2 Python项目环境配置创建一个新的项目目录并初始化虚拟环境。mkdir local-coding-assistant cd local-coding-assistant python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate安装必要的Python包pip install langchain langchain-community langchain-openai requests python-dotenvlangchain: Agent框架核心。langchain-community: 包含社区贡献的各种工具和集成。langchain-openai: 提供了与OpenAI API兼容的客户端我们将用它来连接本地的Ollama服务。requests: 用于可能的额外HTTP请求。python-dotenv: 管理环境变量虽然本项目本地运行但养成好习惯。3.3 核心工具函数实现在项目根目录创建tools.py文件我们将在这里实现所有工具。首先实现最基础的文件操作工具。# tools.py import os import subprocess import sys from typing import Optional, Type from pydantic import BaseModel, Field from langchain.tools import BaseTool, tool # 1. 读取文件工具 class ReadFileInput(BaseModel): 读取文件的输入参数定义。 file_path: str Field(descriptionThe path to the file to read.) tool(args_schemaReadFileInput) def read_file(file_path: str) - str: 读取指定路径文件的内容并返回。 try: with open(file_path, r, encodingutf-8) as f: content f.read() return f文件 {file_path} 的内容如下\n\n{content}\n except FileNotFoundError: return f错误文件 {file_path} 未找到。 except IsADirectoryError: return f错误{file_path} 是一个目录不是文件。 except Exception as e: return f读取文件时发生未知错误{str(e)} # 2. 写入文件工具 class WriteFileInput(BaseModel): 写入文件的输入参数定义。 file_path: str Field(descriptionThe path to the file to write to.) content: str Field(descriptionThe content to write into the file.) mode: str Field(defaultw, descriptionWrite mode: w for overwrite, a for append.) tool(args_schemaWriteFileInput) def write_to_file(file_path: str, content: str, mode: str w) - str: 将内容写入指定路径的文件。模式w为覆盖a为追加。 try: with open(file_path, mode, encodingutf-8) as f: f.write(content) action 覆盖写入 if mode w else 追加写入 return f成功已{action}文件 {file_path}。 except IsADirectoryError: return f错误{file_path} 是一个目录无法写入文件。 except PermissionError: return f错误没有权限写入文件 {file_path}。 except Exception as e: return f写入文件时发生未知错误{str(e)} # 3. 列出目录工具 class ListDirInput(BaseModel): 列出目录的输入参数定义。 dir_path: str Field(default., descriptionThe directory path to list. Default is current directory.) tool(args_schemaListDirInput) def list_directory(dir_path: str .) - str: 列出指定目录下的所有文件和文件夹。 try: items os.listdir(dir_path) # 简单区分文件和文件夹 result [] for item in items: full_path os.path.join(dir_path, item) if os.path.isdir(full_path): result.append(f[目录] {item}/) else: result.append(f[文件] {item}) listing \n.join(result) return f目录 {dir_path} 下的内容\n{listing} except FileNotFoundError: return f错误目录 {dir_path} 未找到。 except NotADirectoryError: return f错误{dir_path} 不是一个有效的目录。 except Exception as e: return f列出目录时发生未知错误{str(e)}实操心得一工具描述Docstring和参数描述Field description是给模型看的“说明书”。一定要写得清晰、准确。模型完全依赖这些描述来决定在什么情况下调用哪个工具以及如何填充参数。例如write_to_file工具中明确说明了mode参数的含义模型在需要追加日志时就会传入modea。3.4 高风险工具的实现与安全考量接下来实现execute_shell_command和python_repl。我们必须格外小心。# tools.py (续) # 4. 执行Shell命令工具高风险 class ShellCommandInput(BaseModel): 执行Shell命令的输入参数定义。 command: str Field(descriptionThe shell command to execute.) timeout: int Field(default30, descriptionCommand execution timeout in seconds.) tool(args_schemaShellCommandInput) def execute_shell_command(command: str, timeout: int 30) - str: 在安全环境下执行一条Shell命令并返回其输出。警告请谨慎使用此工具。 # !!! 安全警告在实际生产部署中此处应有命令白名单、用户权限检查、资源限制和沙箱环境 !!! # 此处仅为演示在受信任的本地环境运行。 print(f[安全警告] 即将执行命令: {command}) try: # 使用subprocess.run可以捕获输出和错误并设置超时 result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeouttimeout, # 可以设置cwd来限制工作目录 # cwd/safe/path ) output [] if result.stdout: output.append(f标准输出\n{result.stdout}) if result.stderr: output.append(f标准错误\n{result.stderr}) output.append(f返回码{result.returncode}) return \n---\n.join(output) except subprocess.TimeoutExpired: return f错误命令执行超时{timeout}秒。 except Exception as e: return f执行命令时发生未知错误{str(e)} # 5. Python REPL工具同样高风险 class PythonREPLInput(BaseModel): 执行Python代码的输入参数定义。 code: str Field(descriptionThe Python code to execute in the REPL.) tool(args_schemaPythonREPLInput) def python_repl(code: str) - str: 在一个独立的、受限的命名空间中执行一段Python代码并返回结果。警告请勿执行危险代码。 # !!! 安全警告这是一个极其强大的工具也是极其危险的。 # 生产环境必须使用Docker容器、资源限制如resource模块、禁用危险模块如os, subprocess等方式进行沙箱化。 # 这里我们做一个简单的限制禁止导入os和subprocess但这并不完全安全。 forbidden_modules [os, subprocess, shutil, sys] for fm in forbidden_modules: if fimport {fm} in code or ffrom {fm} in code: return f安全限制禁止导入模块 {fm}。 local_namespace {} try: # 使用exec执行代码将结果捕获到local_namespace中 exec(code, {__builtins__: __builtins__}, local_namespace) # 尝试获取一个名为_result的变量作为输出这是常见的REPL约定 result local_namespace.get(_result, None) if result is not None: return f代码执行成功。结果\n{repr(result)} else: return 代码执行成功。未设置 _result 变量无显式输出 except Exception as e: return f代码执行出错{type(e).__name__}: {str(e)}实操心得二安全是本地Agent的生命线。我在工具函数里加了大量的print警告和注释。在个人使用中你至少应该做到为execute_shell_command设置一个工作目录白名单比如只允许在/home/yourname/projects下操作。为python_repl使用真正的沙箱例如PyPy的沙箱、restrictedpython或者直接在一个一次性Docker容器中运行代码。上面的简单模块黑名单是远远不够的一个有创造力的模型或恶意指令可能绕过它。永远不要在服务器上未经严格沙箱化就部署此类工具。4. 构建ReAct智能体与主循环工具准备就绪现在用LangChain把它们和本地模型组装起来形成完整的Agent。4.1 连接本地LLM服务创建agent_builder.py文件。# agent_builder.py import os from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain.prompts import PromptTemplate from tools import read_file, write_to_file, list_directory, execute_shell_command, python_repl # 1. 连接到本地Ollama服务 # 注意base_url指向Ollama的OpenAI兼容端点api_key可以任意填写Ollama不校验 llm ChatOpenAI( modelqwen2.5:7b-instruct, # 模型名需要与Ollama拉取的名称一致 base_urlhttp://localhost:11434/v1, api_keyollama, # 任意字符串Ollama不验证 temperature0.1, # 低温度使输出更确定适合工具调用 streamingFalse, # 非流式便于获取完整响应 timeout60, # 设置较长超时模型推理可能需要时间 ) print(✅ 已成功连接到本地LLM服务。)关键参数解析temperature0.1对于工具调用这类需要精确、结构化输出的任务较低的温度值0.1-0.3可以减少模型的随机性让它的思考更聚焦、更可靠。timeout60本地模型推理速度取决于你的硬件复杂的任务可能需要几十秒设置一个较长的超时避免请求中断。4.2 准备工具集和ReAct提示词# agent_builder.py (续) # 2. 组装工具列表 tools [read_file, write_to_file, list_directory, execute_shell_command, python_repl] print(f✅ 已加载 {len(tools)} 个工具。) # 3. 准备ReAct Agent专用的提示词模板 # LangChain有内置的ReAct提示词但我们最好自定义一下让它更适应编程助手的角色。 react_prompt_template 你是一个运行在本地的AI编程助手。你的目标是理解用户的请求并通过调用合适的工具来完成任务。 你可以使用的工具如下 {tools} 使用工具时请严格按照以下格式响应 Thought: 你需要思考现在应该做什么 Action: 要调用的工具名称必须是[{tool_names}]中的一个 Action Input: 调用该工具所需的输入必须是一个合法的JSON字符串 当你拥有足够的信息来回答用户时或者任务完成时你必须使用以下格式 Thought: 我现在可以给出最终答案了 Final Answer: 你的最终回答 历史对话 {history} 开始记住你只能使用上面提供的工具。如果用户请求无法用现有工具完成请礼貌说明。 用户请求{input} {agent_scratchpad} # agent_scratchpad 是LangChain自动填充的用于记录之前的Thought/Action/Observation循环。 prompt PromptTemplate.from_template(react_prompt_template)注意事项提示词Prompt是引导Agent行为的关键。我们明确规定了它的角色编程助手、可用的工具、以及必须遵守的响应格式Thought/Action/Action Input。agent_scratchpad是一个占位符LangChain会在运行时自动将之前的推理-行动-观察记录填充进去形成完整的上下文这是实现多轮循环的基础。4.3 创建Agent执行器并测试# agent_builder.py (续) # 4. 创建ReAct Agent和执行器 agent create_react_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设为True可以看到Agent完整的思考过程调试时非常有用 handle_parsing_errorsTrue, # 当模型输出格式错误时尝试自动修复 max_iterations10, # 限制最大循环次数防止死循环 early_stopping_methodgenerate, # 当模型连续两次输出“Final Answer”时停止 ) print( AI编程助手初始化完成) print(输入 quit 或 exit 退出。) print(- * 50) # 5. 简单的交互循环 def main(): while True: try: user_input input(\n您: ) if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input.strip(): continue print(\n助手正在思考...) # 执行Agent result agent_executor.invoke({input: user_input, history: }) print(f\n助手: {result[output]}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f\n发生错误{e}) if __name__ __main__: main()现在运行python agent_builder.py你应该能看到助手启动并等待你的指令。让我们进行第一次实战测试。5. 实战测试与效果分析理论说得再多不如跑起来看看。我们通过几个典型场景来检验这个本地助手的真实能力并观察其ReAct推理过程。5.1 测试一基础文件操作用户指令“帮我看看当前目录下有什么文件。”预期行为助手应该调用list_directory工具参数dir_path为默认值.。实际运行输出verbose模式您: 帮我看看当前目录下有什么文件。 助手正在思考... Entering new AgentExecutor chain... Thought: 用户想查看当前目录下的文件。我可以使用 list_directory 工具。 Action: list_directory Action Input: {dir_path: .} Observation: 目录 . 下的内容 [文件] agent_builder.py [文件] tools.py [文件] test_project [目录] venv/ Thought: 我已经获取了当前目录的列表可以回答用户了。 Final Answer: 当前目录下有文件 agent_builder.py、tools.py、test_project 以及目录 venv/。 Finished chain. 助手: 当前目录下有文件 agent_builder.py、tools.py、test_project 以及目录 venv/。分析完美助手正确地进行了推理Thought选择了正确的工具Action并传入了合理的参数Action Input。观察Observation到结果后判断任务完成给出了最终答案。整个流程清晰可见。5.2 测试二多步骤代码编写任务用户指令“在项目根目录创建一个名为‘calculator.py’的文件并在里面写一个能计算阶乘的函数factorial(n)要求有类型注解和文档字符串。”这是一个复合任务涉及多个步骤1. 检查/创建文件路径2. 生成代码内容3. 写入文件。实际运行输出节选关键步骤Thought: 用户想要创建一个Python文件并写入一个阶乘函数。我需要先生成函数代码然后写入文件。首先我应该生成代码。 Action: python_repl Action Input: {code: # 生成阶乘函数代码\nimport math\n_result def factorial(n: int) - int:\n \\\计算非负整数n的阶乘。\\\\n if n 0:\n raise ValueError(\阶乘未定义负数\)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n} Observation: 代码执行成功。结果 \ndef factorial(n: int) - int:\n 计算非负整数n的阶乘。\n if n 0:\n raise ValueError(阶乘未定义负数)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n Thought: 代码已生成。现在需要将其写入文件calculator.py。 Action: write_to_file Action Input: {file_path: calculator.py, content: def factorial(n: int) - int:\n \\\计算非负整数n的阶乘。\\\\n if n 0:\n raise ValueError(\阶乘未定义负数\)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n, mode: w} Observation: 成功已覆盖写入文件 calculator.py。 Thought: 文件已创建并写入。现在可以验证一下文件内容。 Action: read_file Action Input: {file_path: calculator.py} Observation: 文件 calculator.py 的内容如下def factorial(n: int) - int: 计算非负整数n的阶乘。 if n 0: raise ValueError(阶乘未定义负数) result 1 for i in range(2, n 1): result * i return resultThought: 验证通过任务完成。 Final Answer: 已成功在 calculator.py 文件中创建了包含类型注解和文档字符串的 factorial 函数。文件内容已通过验证。分析非常精彩助手展现出了优秀的任务分解能力。它没有试图一步到位而是先利用python_repl工具“在脑子里”构思并生成了代码这里巧妙地用_result变量返回了代码字符串然后调用write_to_file写入最后还调用read_file进行了一次验证。这完整地展示了ReAct框架中“思考-行动-观察-再思考”的循环魅力。5.3 测试三复杂调试与交互用户指令“我刚刚写的calculator.py里的factorial函数用5测试一下看看结果对不对。”实际运行输出Thought: 用户想测试calculator.py中的factorial函数。我需要先读取文件内容然后在Python REPL中执行测试。 Action: read_file Action Input: {file_path: calculator.py} Observation: ... (文件内容省略) Thought: 我已经有了函数定义。现在需要在REPL中导入或定义这个函数然后测试factorial(5)。 Action: python_repl Action Input: {code: # 定义factorial函数\ndef factorial(n: int) - int:\n \\\计算非负整数n的阶乘。\\\\n if n 0:\n raise ValueError(\阶乘未定义负数\)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n\n# 进行测试\n_test_result factorial(5)\n_result f\factorial(5) {_test_result}\} Observation: 代码执行成功。结果 factorial(5) 120 Thought: 测试成功结果是120这是正确的5! 120。可以回答用户了。 Final Answer: 测试成功factorial(5) 的计算结果是 120符合预期5的阶乘为120。分析助手不仅执行了测试还进行了一个简单的“事实核查”5! 120并在最终答案中给出了解释。这表明模型具备一定的常识和逻辑验证能力。6. 性能调优、安全加固与常见问题经过基础测试我们的助手已经能跑起来了。但要让它真正可靠、可用还需要解决一些深层次的问题。6.1 性能瓶颈与优化策略推理速度慢7B模型在CPU上推理可能每秒只生成几个token复杂任务等待时间较长。优化方案使用GPU这是最有效的提速方法。确保你的Ollama或vLLM使用了GPU推理。在Ollama中可以通过环境变量OLLAMA_GPU_LAYERS设置使用GPU的层数。模型量化将模型从FP16量化到INT8或INT4可以大幅减少显存占用和提升推理速度精度损失在可接受范围内。Ollama在拉取模型时可以使用ollama run qwen2.5:7b-instruct:q4_K_M来指定量化版本q4_K_M是一种4位量化格式。调整参数降低max_new_tokens最大生成长度和temperature可以加快生成速度。上下文长度限制模型有最大上下文窗口例如Qwen2.5-7B是32K。在长对话或多轮工具调用后历史记录可能超限。优化方案历史摘要实现一个机制将过长的对话历史总结成一段简短的摘要再喂给模型。LangChain提供了ConversationSummaryBufferMemory等记忆组件。选择性记忆只保留最重要的工具调用结果和用户指令丢弃中间冗长的输出。6.2 安全加固的必须措施之前的工具实现只是演示真实使用必须加固。Shell命令执行沙箱化# 增强版的execute_shell_command概念示例 def safe_execute_shell_command(command: str): ALLOWED_COMMANDS [git status, git log, git diff, ls -la, pwd] ALLOWED_PREFIXES [git pull, git fetch, python -m pytest] WORKING_DIR /home/user/safe_projects # 1. 命令白名单检查 if command in ALLOWED_COMMANDS: pass elif any(command.startswith(prefix) for prefix in ALLOWED_PREFIXES): pass else: return 错误该命令不在允许的白名单内。 # 2. 使用subprocess在受限目录下运行 try: result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeout30, cwdWORKING_DIR, # 限制工作目录 # 可以设置用户/组ID来降低权限 # preexec_fndemote_user ) # ... 返回结果 except ...: # ... 异常处理Python REPL沙箱化考虑使用docker run --rm -v $(pwd):/code python:3.11-slim python -c “user_code”的方式在一次性容器中运行用户代码并限制网络、内存和CPU。文件路径限制在所有文件操作工具中检查file_path是否为绝对路径或者是否试图访问系统目录如/etc,/root。可以强制将所有路径解析为相对于某个安全基目录的路径。6.3 常见问题与排查技巧实录在实际操作中你几乎一定会遇到以下问题。这里是我的排查记录问题1模型不调用工具而是直接生成回答。现象对于“列出目录”这样的指令模型直接回答“我可以帮你列出目录但我现在没有访问文件系统的能力...”而不是触发list_directory工具。原因提示词Prompt不够强硬或者模型的Function Calling能力未充分激发。也可能是temperature设置过高导致输出随机。解决在提示词中强调“你必须使用提供的工具来完成任务”“你只能使用以下工具”。检查使用的模型是否确实是支持工具调用的指令微调版-Instruct。将temperature降至0.1。使用LangChain的bind_tools()方法如果LLM支持来显式绑定工具schema这比纯文本提示更可靠。问题2模型输出了正确的Action和Action Input但格式解析失败。现象LangChain报错OutputParserException: Could not parse LLM output: ...。原因模型的输出可能有多余的空格、换行或标记导致LangChain的正则表达式无法正确提取Action:和Action Input:后面的内容。解决设置AgentExecutor(handle_parsing_errorsTrue)让执行器尝试自动修复或重试。在提示词中用三个反引号明确标出JSON格式例如Action Input: {file_path: test.txt}如果问题持续可以编写一个自定义的输出解析器适应你特定模型的输出风格。问题3Agent陷入死循环。现象Agent反复调用同一个工具或者在不同的工具间来回切换无法达到最终状态。原因工具返回的结果可能模棱两可或者模型无法从结果中判断任务是否完成。解决设置AgentExecutor(max_iterations10)强制限制循环次数。优化工具的输出使其更清晰、更具结论性。例如read_file在文件不存在时明确返回“错误文件未找到”而不是一个空字符串。在提示词中加强引导告诉模型在什么情况下应该给出“Final Answer”。例如“如果你已经成功创建了文件并验证了内容那么任务就完成了请给出最终答案。”问题4工具调用结果太长挤爆上下文。现象执行ls -la在一个大目录下或者读取一个很大的文件返回的Observation文本非常长导致下一次模型调用时上下文超限模型表现异常。解决为工具输出增加截断逻辑。例如只返回文件的前100行或目录列表的前50个条目并附加“内容已截断...”。使用具有更长上下文的模型如Qwen2.5-32K。如前所述实现历史摘要功能。构建这个本地编程助手的过程就像在教一个聪明的实习生如何正确使用电脑。你需要定义清晰的规则工具、提供明确的说明书提示词、并时刻关注它的操作Verbose模式。虽然它偶尔会犯傻或陷入循环但当你看到它能够自主地完成一个多步骤的编程任务时那种成就感是巨大的。这个项目不仅是一个实用工具更是一个理解AI Agent如何“思考”和“行动”的绝佳窗口。你可以基于这个框架轻松地添加更多工具比如“调用HTTP API”、“查询数据库”、“生成图表”将它扩展成你的专属自动化助手。 1. 项目概述为什么我们需要一个本地编程助手最近在折腾一个个人项目需要频繁地在不同编程语言和框架之间切换查文档、写示例代码、调试错误一套流程下来感觉时间都花在了“找”和“试”上而不是真正的“思考”和“创造”。相信很多开发者都有同感我们的大脑CPU不应该被搜索引擎的加载速度和API文档的跳转所占据。市面上的云端AI编程助手固然强大但涉及到公司代码、私有协议或者对网络延迟敏感的场景时总感觉束手束脚数据安全和响应速度都是问题。于是一个想法冒了出来能不能自己动手打造一个完全运行在本地的AI编程助手它不依赖任何外部API能理解我的自然语言指令调用本地工具比如代码解释器、文件系统、Git命令来完成任务并且整个思考过程对我透明。这不就是AI Agent的典型场景吗而实现它的核心技术正是当前大模型应用开发中的两个热门范式ReActReasoning Acting和Function Calling函数调用。这个项目就是一次将这两个概念落地的实战。我们将基于一个可以在本地部署的大语言模型LLM构建一个具备自主推理和行动能力的智能体Agent。它不仅能和你对话更能根据你的指令规划步骤、调用我们预先定义好的工具函数比如“写一个Python函数”、“在指定文件末尾添加代码”、“运行这段Shell命令并返回结果”并循环这个过程直到任务完成。最终你会得到一个完全受你控制、能力可无限扩展的“编程副驾驶”。接下来我将详细拆解从零到一构建这个本地助手的全过程包括核心原理、工具链选型、每一步的实操代码以及我踩过的那些坑。2. 核心架构与工具链选型构建一个AI Agent尤其是本地化的选型是第一步它直接决定了项目的可行性、性能和开发体验。我们需要一个清晰的架构并为其挑选合适的“零部件”。2.1 整体架构设计我们的本地编程助手核心是一个智能体循环。它的工作流程可以抽象为以下几步接收指令用户提出一个自然语言请求例如“在./src/utils.py文件里帮我写一个计算斐波那契数列的函数并添加对应的类型注解和文档字符串。”模型推理Reason本地大模型分析指令理解用户的意图并规划出下一步需要执行的动作Action。例如它可能推理出“用户需要我写代码。我应该先检查目标文件是否存在然后生成符合要求的函数代码最后将代码写入文件。”执行动作Act模型根据规划决定调用哪个工具Tool并生成调用该工具所需的参数。例如调用write_to_file工具参数为file_path“./src/utils.py”和content生成的代码。观察结果Observe工具执行后将结果成功或失败附带输出信息返回给模型。循环判断模型根据观察到的结果判断任务是否完成。如果未完成例如文件不存在需要先创建则回到第2步进行下一轮的推理和行动直到任务完成为止。这个“推理Reason- 行动Act- 观察Observe”的循环就是ReAct框架的核心思想。而Function Calling则是实现“行动Act”环节的关键技术它让大模型能够以结构化的方式调用我们预先定义好的函数。2.2 核心组件选型解析1. 大语言模型LLM本地运行的“大脑”这是Agent的智能核心。选择本地模型主要考虑三点性能足够强、支持Function Calling、硬件资源友好。为什么不是ChatGPT/Claude它们虽然功能强大但需要网络和API密钥无法满足“完全本地、数据不出境”的核心需求。备选模型Qwen2.5-7B-Instruct、Llama 3.1-8B-Instruct、DeepSeek-Coder-V2-Lite。这些模型在代码能力、指令跟随和工具调用方面表现不错且参数量在7B-16B之间在消费级显卡如RTX 4060 16GB上可以流畅运行。最终选择我选择了Qwen2.5-7B-Instruct。原因如下首先它的工具调用Function Calling能力经过专门优化格式规范响应稳定。其次7B的参数量对硬件要求相对友好通过量化技术如GPTQ、AWQ可以在8GB显存上运行。最后它的中英文代码和理解能力比较均衡适合我的使用场景。注意事项务必下载带有-Instruct后缀的版本这是经过对话和指令微调的对于理解用户意图和遵循ReAct格式至关重要。原始预训练模型Base Model通常不具备这么好的指令跟随能力。2. 模型推理框架如何高效运行模型我们需要一个库来加载模型、处理对话、并管理生成过程。为什么不是直接调用transformers虽然可以但我们需要自己处理聊天模板、历史记录、停止词等比较繁琐。主流选择vLLM追求极致吞吐、llama.cpp追求极致轻量和CPU推理、Ollama开箱即用的管理工具、LM Studio图形化界面。最终选择我使用Ollama作为本地模型服务。它极其简单一条命令就能拉取和运行模型并且内置了OpenAI兼容的API接口http://localhost:11434/v1这让我们后续可以使用标准的OpenAI SDK来调用它大大简化了开发。命令很简单ollama run qwen2.5:7b-instruct。对于更注重控制和生产环境我会用vLLM部署但Ollama在原型开发和个人使用中体验最佳。3. Agent开发框架实现ReAct循环的“脚手架”手动实现ReAct循环、工具管理、历史追踪是个复杂工程。使用成熟的Agent框架可以事半功倍。为什么需要框架它们封装了Agent的核心循环、工具调用、记忆管理等通用逻辑我们只需关注定义工具和任务本身。主流选择LangChain/LangGraph生态强大但稍显臃肿、LlamaIndex擅长与数据结合、Microsoft Autogen多Agent协作、CrewAI面向工作流。最终选择我选择了LangChain。虽然它被诟病“抽象泄漏”你需要了解其底层但其社区活跃、文档丰富、工具集成度最高。对于这个项目我们主要使用它的Agent、Tools和OpenAI兼容模块。它的create_react_agent函数能直接帮我们构建一个标准的ReAct Agent。4. 工具Tools定义Agent的“手和脚”这是赋予Agent能力的关键。我们将用Python函数来定义工具并用装饰器告诉LangChain这些是可被调用的工具。核心工具规划execute_shell_command: 执行Shell命令并返回输出用于运行脚本、Git操作等。read_file: 读取指定文件的内容。write_to_file: 向指定文件写入内容覆盖或追加。list_directory: 列出指定目录下的文件和文件夹。python_repl: 一个安全的Python交互式环境用于执行代码片段并返回结果这是代码助手的核心。安全警告execute_shell_command和python_repl是高风险工具必须施加严格的沙箱或权限限制。在个人开发环境中我们基于信任但仍建议避免赋予其删除根目录、格式化磁盘等危险操作的权限。在生产环境中必须使用 Docker 容器、资源限制和命令白名单等机制进行隔离。3. 环境搭建与基础工具实现理论清晰后我们开始动手。首先确保你的开发环境已经就绪。3.1 本地模型服务部署安装Ollama访问Ollama官网根据你的操作系统Windows/macOS/Linux下载并安装。拉取并运行模型打开终端执行以下命令。这会自动下载模型并启动一个本地API服务。ollama run qwen2.5:7b-instruct首次运行需要下载约4.5GB的模型文件。运行成功后终端会保持运行状态API服务在http://localhost:11434就绪。验证API打开另一个终端用curl测试一下。curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b-instruct, messages: [{role: user, content: Hello, write a simple Python function to add two numbers.}], stream: false }如果看到返回一个包含AI回复的JSON说明模型服务运行正常。3.2 Python项目环境配置创建一个新的项目目录并初始化虚拟环境。mkdir local-coding-assistant cd local-coding-assistant python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate安装必要的Python包pip install langchain langchain-community langchain-openai requests python-dotenvlangchain: Agent框架核心。langchain-community: 包含社区贡献的各种工具和集成。langchain-openai: 提供了与OpenAI API兼容的客户端我们将用它来连接本地的Ollama服务。requests: 用于可能的额外HTTP请求。python-dotenv: 管理环境变量虽然本项目本地运行但养成好习惯。3.3 核心工具函数实现在项目根目录创建tools.py文件我们将在这里实现所有工具。首先实现最基础的文件操作工具。# tools.py import os import subprocess import sys from typing import Optional, Type from pydantic import BaseModel, Field from langchain.tools import BaseTool, tool # 1. 读取文件工具 class ReadFileInput(BaseModel): 读取文件的输入参数定义。 file_path: str Field(descriptionThe path to the file to read.) tool(args_schemaReadFileInput) def read_file(file_path: str) - str: 读取指定路径文件的内容并返回。 try: with open(file_path, r, encodingutf-8) as f: content f.read() return f文件 {file_path} 的内容如下\n\n{content}\n except FileNotFoundError: return f错误文件 {file_path} 未找到。 except IsADirectoryError: return f错误{file_path} 是一个目录不是文件。 except Exception as e: return f读取文件时发生未知错误{str(e)} # 2. 写入文件工具 class WriteFileInput(BaseModel): 写入文件的输入参数定义。 file_path: str Field(descriptionThe path to the file to write to.) content: str Field(descriptionThe content to write into the file.) mode: str Field(defaultw, descriptionWrite mode: w for overwrite, a for append.) tool(args_schemaWriteFileInput) def write_to_file(file_path: str, content: str, mode: str w) - str: 将内容写入指定路径的文件。模式w为覆盖a为追加。 try: with open(file_path, mode, encodingutf-8) as f: f.write(content) action 覆盖写入 if mode w else 追加写入 return f成功已{action}文件 {file_path}。 except IsADirectoryError: return f错误{file_path} 是一个目录无法写入文件。 except PermissionError: return f错误没有权限写入文件 {file_path}。 except Exception as e: return f写入文件时发生未知错误{str(e)} # 3. 列出目录工具 class ListDirInput(BaseModel): 列出目录的输入参数定义。 dir_path: str Field(default., descriptionThe directory path to list. Default is current directory.) tool(args_schemaListDirInput) def list_directory(dir_path: str .) - str: 列出指定目录下的所有文件和文件夹。 try: items os.listdir(dir_path) # 简单区分文件和文件夹 result [] for item in items: full_path os.path.join(dir_path, item) if os.path.isdir(full_path): result.append(f[目录] {item}/) else: result.append(f[文件] {item}) listing \n.join(result) return f目录 {dir_path} 下的内容\n{listing} except FileNotFoundError: return f错误目录 {dir_path} 未找到。 except NotADirectoryError: return f错误{dir_path} 不是一个有效的目录。 except Exception as e: return f列出目录时发生未知错误{str(e)}实操心得一工具描述Docstring和参数描述Field description是给模型看的“说明书”。一定要写得清晰、准确。模型完全依赖这些描述来决定在什么情况下调用哪个工具以及如何填充参数。例如write_to_file工具中明确说明了mode参数的含义模型在需要追加日志时就会传入modea。3.4 高风险工具的实现与安全考量接下来实现execute_shell_command和python_repl。我们必须格外小心。# tools.py (续) # 4. 执行Shell命令工具高风险 class ShellCommandInput(BaseModel): 执行Shell命令的输入参数定义。 command: str Field(descriptionThe shell command to execute.) timeout: int Field(default30, descriptionCommand execution timeout in seconds.) tool(args_schemaShellCommandInput) def execute_shell_command(command: str, timeout: int 30) - str: 在安全环境下执行一条Shell命令并返回其输出。警告请谨慎使用此工具。 # !!! 安全警告在实际生产部署中此处应有命令白名单、用户权限检查、资源限制和沙箱环境 !!! # 此处仅为演示在受信任的本地环境运行。 print(f[安全警告] 即将执行命令: {command}) try: # 使用subprocess.run可以捕获输出和错误并设置超时 result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeouttimeout, # 可以设置cwd来限制工作目录 # cwd/safe/path ) output [] if result.stdout: output.append(f标准输出\n{result.stdout}) if result.stderr: output.append(f标准错误\n{result.stderr}) output.append(f返回码{result.returncode}) return \n---\n.join(output) except subprocess.TimeoutExpired: return f错误命令执行超时{timeout}秒。 except Exception as e: return f执行命令时发生未知错误{str(e)} # 5. Python REPL工具同样高风险 class PythonREPLInput(BaseModel): 执行Python代码的输入参数定义。 code: str Field(descriptionThe Python code to execute in the REPL.) tool(args_schemaPythonREPLInput) def python_repl(code: str) - str: 在一个独立的、受限的命名空间中执行一段Python代码并返回结果。警告请勿执行危险代码。 # !!! 安全警告这是一个极其强大的工具也是极其危险的。 # 生产环境必须使用Docker容器、资源限制如resource模块、禁用危险模块如os, subprocess等方式进行沙箱化。 # 这里我们做一个简单的限制禁止导入os和subprocess但这并不完全安全。 forbidden_modules [os, subprocess, shutil, sys] for fm in forbidden_modules: if fimport {fm} in code or ffrom {fm} in code: return f安全限制禁止导入模块 {fm}。 local_namespace {} try: # 使用exec执行代码将结果捕获到local_namespace中 exec(code, {__builtins__: __builtins__}, local_namespace) # 尝试获取一个名为_result的变量作为输出这是常见的REPL约定 result local_namespace.get(_result, None) if result is not None: return f代码执行成功。结果\n{repr(result)} else: return 代码执行成功。未设置 _result 变量无显式输出 except Exception as e: return f代码执行出错{type(e).__name__}: {str(e)}实操心得二安全是本地Agent的生命线。我在工具函数里加了大量的print警告和注释。在个人使用中你至少应该做到为execute_shell_command设置一个工作目录白名单比如只允许在/home/yourname/projects下操作。为python_repl使用真正的沙箱例如PyPy的沙箱、restrictedpython或者直接在一个一次性Docker容器中运行代码。上面的简单模块黑名单是远远不够的一个有创造力的模型或恶意指令可能绕过它。永远不要在服务器上未经严格沙箱化就部署此类工具。4. 构建ReAct智能体与主循环工具准备就绪现在用LangChain把它们和本地模型组装起来形成完整的Agent。4.1 连接本地LLM服务创建agent_builder.py文件。# agent_builder.py import os from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain.prompts import PromptTemplate from tools import read_file, write_to_file, list_directory, execute_shell_command, python_repl # 1. 连接到本地Ollama服务 # 注意base_url指向Ollama的OpenAI兼容端点api_key可以任意填写Ollama不校验 llm ChatOpenAI( modelqwen2.5:7b-instruct, # 模型名需要与Ollama拉取的名称一致 base_urlhttp://localhost:11434/v1, api_keyollama, # 任意字符串Ollama不验证 temperature0.1, # 低温度使输出更确定适合工具调用 streamingFalse, # 非流式便于获取完整响应 timeout60, # 设置较长超时模型推理可能需要时间 ) print(✅ 已成功连接到本地LLM服务。)关键参数解析temperature0.1对于工具调用这类需要精确、结构化输出的任务较低的温度值0.1-0.3可以减少模型的随机性让它的思考更聚焦、更可靠。timeout60本地模型推理速度取决于你的硬件复杂的任务可能需要几十秒设置一个较长的超时避免请求中断。4.2 准备工具集和ReAct提示词# agent_builder.py (续) # 2. 组装工具列表 tools [read_file, write_to_file, list_directory, execute_shell_command, python_repl] print(f✅ 已加载 {len(tools)} 个工具。) # 3. 准备ReAct Agent专用的提示词模板 # LangChain有内置的ReAct提示词但我们最好自定义一下让它更适应编程助手的角色。 react_prompt_template 你是一个运行在本地的AI编程助手。你的目标是理解用户的请求并通过调用合适的工具来完成任务。 你可以使用的工具如下 {tools} 使用工具时请严格按照以下格式响应 Thought: 你需要思考现在应该做什么 Action: 要调用的工具名称必须是[{tool_names}]中的一个 Action Input: 调用该工具所需的输入必须是一个合法的JSON字符串 当你拥有足够的信息来回答用户时或者任务完成时你必须使用以下格式 Thought: 我现在可以给出最终答案了 Final Answer: 你的最终回答 历史对话 {history} 开始记住你只能使用上面提供的工具。如果用户请求无法用现有工具完成请礼貌说明。 用户请求{input} {agent_scratchpad} # agent_scratchpad 是LangChain自动填充的用于记录之前的Thought/Action/Observation循环。 prompt PromptTemplate.from_template(react_prompt_template)注意事项提示词Prompt是引导Agent行为的关键。我们明确规定了它的角色编程助手、可用的工具、以及必须遵守的响应格式Thought/Action/Action Input。agent_scratchpad是一个占位符LangChain会在运行时自动将之前的推理-行动-观察记录填充进去形成完整的上下文这是实现多轮循环的基础。4.3 创建Agent执行器并测试# agent_builder.py (续) # 4. 创建ReAct Agent和执行器 agent create_react_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设为True可以看到Agent完整的思考过程调试时非常有用 handle_parsing_errorsTrue, # 当模型输出格式错误时尝试自动修复 max_iterations10, # 限制最大循环次数防止死循环 early_stopping_methodgenerate, # 当模型连续两次输出“Final Answer”时停止 ) print( AI编程助手初始化完成) print(输入 quit 或 exit 退出。) print(- * 50) # 5. 简单的交互循环 def main(): while True: try: user_input input(\n您: ) if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input.strip(): continue print(\n助手正在思考...) # 执行Agent result agent_executor.invoke({input: user_input, history: }) print(f\n助手: {result[output]}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f\n发生错误{e}) if __name__ __main__: main()现在运行python agent_builder.py你应该能看到助手启动并等待你的指令。让我们进行第一次实战测试。5. 实战测试与效果分析理论说得再多不如跑起来看看。我们通过几个典型场景来检验这个本地助手的真实能力并观察其ReAct推理过程。5.1 测试一基础文件操作用户指令“帮我看看当前目录下有什么文件。”预期行为助手应该调用list_directory工具参数dir_path为默认值.。实际运行输出verbose模式您: 帮我看看当前目录下有什么文件。 助手正在思考... Entering new AgentExecutor chain... Thought: 用户想查看当前目录下的文件。我可以使用 list_directory 工具。 Action: list_directory Action Input: {dir_path: .} Observation: 目录 . 下的内容 [文件] agent_builder.py [文件] tools.py [文件] test_project [目录] venv/ Thought: 我已经获取了当前目录的列表可以回答用户了。 Final Answer: 当前目录下有文件 agent_builder.py、tools.py、test_project 以及目录 venv/。 Finished chain. 助手: 当前目录下有文件 agent_builder.py、tools.py、test_project 以及目录 venv/。分析完美助手正确地进行了推理Thought选择了正确的工具Action并传入了合理的参数Action Input。观察Observation到结果后判断任务完成给出了最终答案。整个流程清晰可见。5.2 测试二多步骤代码编写任务用户指令“在项目根目录创建一个名为‘calculator.py’的文件并在里面写一个能计算阶乘的函数factorial(n)要求有类型注解和文档字符串。”这是一个复合任务涉及多个步骤1. 检查/创建文件路径2. 生成代码内容3. 写入文件。实际运行输出节选关键步骤Thought: 用户想要创建一个Python文件并写入一个阶乘函数。我需要先生成函数代码然后写入文件。首先我应该生成代码。 Action: python_repl Action Input: {code: # 生成阶乘函数代码\nimport math\n_result def factorial(n: int) - int:\n \\\计算非负整数n的阶乘。\\\\n if n 0:\n raise ValueError(\阶乘未定义负数\)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n} Observation: 代码执行成功。结果 \ndef factorial(n: int) - int:\n 计算非负整数n的阶乘。\n if n 0:\n raise ValueError(阶乘未定义负数)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n Thought: 代码已生成。现在需要将其写入文件calculator.py。 Action: write_to_file Action Input: {file_path: calculator.py, content: def factorial(n: int) - int:\n \\\计算非负整数n的阶乘。\\\\n if n 0:\n raise ValueError(\阶乘未定义负数\)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n, mode: w} Observation: 成功已覆盖写入文件 calculator.py。 Thought: 文件已创建并写入。现在可以验证一下文件内容。 Action: read_file Action Input: {file_path: calculator.py} Observation: 文件 calculator.py 的内容如下def factorial(n: int) - int: 计算非负整数n的阶乘。 if n 0: raise ValueError(阶乘未定义负数) result 1 for i in range(2, n 1): result * i return resultThought: 验证通过任务完成。 Final Answer: 已成功在 calculator.py 文件中创建了包含类型注解和文档字符串的 factorial 函数。文件内容已通过验证。分析非常精彩助手展现出了优秀的任务分解能力。它没有试图一步到位而是先利用python_repl工具“在脑子里”构思并生成了代码这里巧妙地用_result变量返回了代码字符串然后调用write_to_file写入最后还调用read_file进行了一次验证。这完整地展示了ReAct框架中“思考-行动-观察-再思考”的循环魅力。5.3 测试三复杂调试与交互用户指令“我刚刚写的calculator.py里的factorial函数用5测试一下看看结果对不对。”实际运行输出Thought: 用户想测试calculator.py中的factorial函数。我需要先读取文件内容然后在Python REPL中执行测试。 Action: read_file Action Input: {file_path: calculator.py} Observation: ... (文件内容省略) Thought: 我已经有了函数定义。现在需要在REPL中导入或定义这个函数然后测试factorial(5)。 Action: python_repl Action Input: {code: # 定义factorial函数\ndef factorial(n: int) - int:\n \\\计算非负整数n的阶乘。\\\\n if n 0:\n raise ValueError(\阶乘未定义负数\)\n result 1\n for i in range(2, n 1):\n result * i\n return result\n\n# 进行测试\n_test_result factorial(5)\n_result f\factorial(5) {_test_result}\} Observation: 代码执行成功。结果 factorial(5) 120 Thought: 测试成功结果是120这是正确的5! 120。可以回答用户了。 Final Answer: 测试成功factorial(5) 的计算结果是 120符合预期5的阶乘为120。分析助手不仅执行了测试还进行了一个简单的“事实核查”5! 120并在最终答案中给出了解释。这表明模型具备一定的常识和逻辑验证能力。6. 性能调优、安全加固与常见问题经过基础测试我们的助手已经能跑起来了。但要让它真正可靠、可用还需要解决一些深层次的问题。6.1 性能瓶颈与优化策略推理速度慢7B模型在CPU上推理可能每秒只生成几个token复杂任务等待时间较长。优化方案使用GPU这是最有效的提速方法。确保你的Ollama或vLLM使用了GPU推理。在Ollama中可以通过环境变量OLLAMA_GPU_LAYERS设置使用GPU的层数。模型量化将模型从FP16量化到INT8或INT4可以大幅减少显存占用和提升推理速度精度损失在可接受范围内。Ollama在拉取模型时可以使用ollama run qwen2.5:7b-instruct:q4_K_M来指定量化版本q4_K_M是一种4位量化格式。调整参数降低max_new_tokens最大生成长度和temperature可以加快生成速度。上下文长度限制模型有最大上下文窗口例如Qwen2.5-7B是32K。在长对话或多轮工具调用后历史记录可能超限。优化方案历史摘要实现一个机制将过长的对话历史总结成一段简短的摘要再喂给模型。LangChain提供了ConversationSummaryBufferMemory等记忆组件。选择性记忆只保留最重要的工具调用结果和用户指令丢弃中间冗长的输出。6.2 安全加固的必须措施之前的工具实现只是演示真实使用必须加固。Shell命令执行沙箱化# 增强版的execute_shell_command概念示例 def safe_execute_shell_command(command: str): ALLOWED_COMMANDS [git status, git log, git diff, ls -la, pwd] ALLOWED_PREFIXES [git pull, git fetch, python -m pytest] WORKING_DIR /home/user/safe_projects # 1. 命令白名单检查 if command in ALLOWED_COMMANDS: pass elif any(command.startswith(prefix) for prefix in ALLOWED_PREFIXES): pass else: return 错误该命令不在允许的白名单内。 # 2. 使用subprocess在受限目录下运行 try: result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeout30, cwdWORKING_DIR, # 限制工作目录 # 可以设置用户/组ID来降低权限 # preexec_fndemote_user ) # ... 返回结果 except ...: # ... 异常处理Python REPL沙箱化考虑使用docker run --rm -v $(pwd):/code python:3.11-slim python -c “user_code”的方式在一次性容器中运行用户代码并限制网络、内存和CPU。文件路径限制在所有文件操作工具中检查file_path是否为绝对路径或者是否试图访问系统目录如/etc,/root。可以强制将所有路径解析为相对于某个安全基目录的路径。6.3 常见问题与排查技巧实录在实际操作中你几乎一定会遇到以下问题。这里是我的排查记录问题1模型不调用工具而是直接生成回答。现象对于“列出目录”这样的指令模型直接回答“我可以帮你列出目录但我现在没有访问文件系统的能力...”而不是触发list_directory工具。原因提示词Prompt不够强硬或者模型的Function Calling能力未充分激发。也可能是temperature设置过高导致输出随机。解决在提示词中强调“你必须使用提供的工具来完成任务”“你只能使用以下工具”。检查使用的模型是否确实是支持工具调用的指令微调版-Instruct。将temperature降至0.1。使用LangChain的bind_tools()方法如果LLM支持来显式绑定工具schema这比纯文本提示更可靠。问题2模型输出了正确的Action和Action Input但格式解析失败。现象LangChain报错OutputParserException: Could not parse LLM output: ...。原因模型的输出可能有多余的空格、换行或标记导致LangChain的正则表达式无法正确提取Action:和Action Input:后面的内容。解决设置AgentExecutor(handle_parsing_errorsTrue)让执行器尝试自动修复或重试。在提示词中用三个反引号明确标出JSON格式例如Action Input: {file_path: test.txt}如果问题持续可以编写一个自定义的输出解析器适应你特定模型的输出风格。问题3Agent陷入死循环。现象Agent反复调用同一个工具或者在不同的工具间来回切换无法达到最终状态。原因工具返回的结果可能模棱两可或者模型无法从结果中判断任务是否完成。解决设置AgentExecutor(max_iterations10)强制限制循环次数。优化工具的输出使其更清晰、更具结论性。例如read_file在文件不存在时明确返回“错误文件未找到”而不是一个空字符串。在提示词中加强引导告诉模型在什么情况下应该给出“Final Answer”。例如“如果你已经成功创建了文件并验证了内容那么任务就完成了请给出最终答案。”问题4工具调用结果太长挤爆上下文。现象执行ls -la在一个大目录下或者读取一个很大的文件返回的Observation文本非常长导致下一次模型调用时上下文超限模型表现异常。解决为工具输出增加截断逻辑。例如只返回文件的前100行或目录列表的前50个条目并附加“内容已截断...”。使用具有更长上下文的模型如Qwen2.5-32K。如前所述实现历史摘要功能。构建这个本地编程助手的过程就像在教一个聪明的实习生如何正确使用电脑。你需要定义清晰的规则工具、提供明确的说明书提示词、并时刻关注它的操作Verbose模式。虽然它偶尔会犯傻或陷入循环但当你看到它能够自主地完成一个多步骤的编程任务时那种成就感是巨大的。这个项目不仅是一个实用工具更是一个理解AI Agent如何“思考”和“行动”的绝佳窗口。你可以基于这个框架轻松地添加更多工具比如“调用HTTP API”、“查询数据库”、“生成图表”将它扩展成你的专属自动化助手。 
