1. 项目概述为什么“LLM文件编写”是当下最值得投入的技能如果你最近在关注AI应用开发尤其是大语言模型LLM的落地那么“LLM文件编写”这个词组一定高频出现在你的视野里。它听起来可能有点技术化甚至有些枯燥但我想告诉你这恰恰是连接创意想法与可运行AI应用之间最核心、最实用、也最容易被忽视的桥梁。简单来说LLM文件编写就是一套“告诉AI如何思考和行动”的标准化说明书。它不是简单的聊天也不是写几行代码调用API而是通过结构化的文档定义LLM的角色Skill、思考流程Prompt模板、可用工具Tool配置以及知识边界RAG/知识库。为什么说它从“入门”到“精通”的路径如此重要因为当前的LLM应用开发正从早期的“炫技式对话”走向深度的“生产级集成”。一个能聊天的AI助理和一個能自动处理工单、分析报表、生成合规文档的AI员工其核心区别就在于后者拥有一套精心设计的“操作手册”——也就是我们所说的LLM文件。无论是使用LangChain、Dify、FastAPI自建框架还是直接调用Claude、GPT的API最终决定应用智能上限和稳定性的往往不是模型本身而是开发者编写的这些配置文件、提示词模板和工具定义。我见过太多项目初期模型选型很酷架构图画得很漂亮但一进入实际开发团队就在“如何让AI准确理解业务逻辑”、“如何让AI稳定调用外部工具”、“如何管理复杂的多轮对话状态”这些问题上反复踩坑。其根源大多是对LLM文件编写缺乏系统性的认知和实践。掌握这项技能意味着你能将模糊的需求转化为AI可执行的精确指令能设计出高效、可靠且易于维护的AI工作流Workflow能真正释放LLM在垂直领域的潜力。接下来我将结合我踩过的坑和总结的经验为你拆解从入门到精通的全路径。2. 核心概念拆解Skill, Prompt, Tool, Agent 到底是什么关系刚接触时这些术语容易让人混淆。我们可以把它们想象成一个AI特工Agent的装备和训练手册。2.1 Skill技能/角色定义AI的“人设”与核心能力集Skill是LLM文件的顶层设计它定义了AI在特定任务中的身份、目标和能力边界。这不是一句“你是一个有帮助的助手”那么简单。一个精良的Skill定义通常包含身份与背景明确、具体的角色。例如“你是一名拥有10年经验的跨境电商客服专家擅长处理物流纠纷和退款申请语气专业且富有同理心。”核心职责与目标清晰的任务范围。例如“你的核心目标是安抚用户情绪快速定位物流问题节点并根据公司政策提供解决方案选项最终目标是提升客户满意度避免升级投诉。”约束与边界防止AI“胡说八道”或越界。例如“你只能处理订单创建后90天内的物流查询。对于产品质量问题应引导用户联系质检部门。严禁对用户做出无法兑现的承诺如‘明天一定送到’。”输出格式规范确保结果能被下游系统处理。例如“你的回复必须是一个JSON对象包含problem_type问题分类、suggested_solutions解决方案数组和next_step建议用户操作三个字段。”实操心得定义Skill时最忌讳宽泛。越具体AI的表现越稳定。我通常会为同一个应用设计多个细分的Skill比如“售前咨询Skill”、“售后工单Skill”、“数据查询Skill”而不是试图用一个“万能助理Skill”解决所有问题。2.2 Prompt模板提示词模板AI的“思考框架”与上下文管理器如果说Skill是战略Prompt模板就是战术脚本。它是在Skill框架下针对具体对话轮次或任务步骤设计的结构化输入。一个高效的Prompt模板远不止是用户问题的前缀。它通常由以下几部分组成系统指令System Message重申或细化当前步骤的Skill要求。这部分通常固定放在对话开头。上下文Context动态注入的信息如本次对话的历史记录、从知识库检索到的相关文档、从数据库查询到的用户订单数据等。这是实现“记忆”和“精准”的关键。用户输入User Input当前用户的问题或指令。输出指示Output Indicator明确告诉AI以何种形式思考和组织答案。例如“请按以下步骤分析1. 识别用户情绪2. 提取关键实体订单号、问题类型3. 匹配知识库条款4. 生成回复。”2.3 Tool配置工具调用配置AI的“手脚”与外部世界连接器LLM本身是“大脑”它需要“手脚”Tools来执行具体操作比如查询数据库、调用API、发送邮件、生成图表。Tool配置就是定义这些手脚如何工作。一个Tool配置通常包括工具名称与描述用自然语言清晰描述工具的功能这本身就是给LLM的“使用说明书”。例如“query_order_status根据用户提供的订单号从公司订单数据库中查询最新的物流状态和预计送达时间。”输入参数模式Schema严格定义工具需要的输入参数名称、类型、是否必填、描述。这通常用JSON Schema定义。例如order_id字符串必填。执行函数/API端点工具被调用时实际执行的代码函数或HTTP请求。授权与错误处理工具调用所需的认证信息如API Key以及调用失败时的回退策略。2.4 Agent与WorkflowSkill、Prompt、Tool的编排与调度当单个Skill和Tool无法完成复杂任务时就需要Agent和Workflow。你可以把Agent看作一个具备自主规划能力的“经理”它根据目标决定调用哪个Skill使用哪些Tool并管理整个执行流程。基于LLM的Agent例如使用LangGraph或AutoGen框架让一个“规划Agent”先拆解任务然后调用不同的“执行Agent”每个对应一个Skill和Tools。基于规则的Workflow例如在Dify、LangChain中可视化的流程设计器。你可以拖拽节点定义清晰的执行路径先触发Skill A然后调用Tool B查询数据再将结果注入Prompt模板C最后生成输出。这种方式更可控适合流程固定的任务。它们的关系总结Skill定义了AI是谁、要做什么Prompt模板指导它在具体场景中如何思考Tool赋予它行动的能力而Agent/Workflow则将这一切串联起来完成从“思考”到“行动”的闭环。编写LLM文件本质上就是在精心设计这套“特工装备系统”。3. 从零开始你的第一个LLM文件编写实战理论说了这么多我们直接动手创建一个简单的“技术文档助手”Skill。我们将定义它的角色、设计一个Prompt模板并为其配置一个搜索工具。3.1 环境与工具准备我们不依赖任何重型框架以最通用的方式开始。你需要一个LLM API访问权限例如OpenAI GPT、Claude、或国内可用的主流模型API。一个代码编辑器VS Code、PyCharm等皆可。Python环境安装requests库用于调用API和工具。3.2 第一步编写Skill定义skill_definition.yaml我们采用YAML格式因为它结构清晰易于阅读和版本管理。# skill_definition.yaml name: tech_doc_assistant version: 1.0 description: 一个专注于回答编程语言和框架相关技术问题的助手。擅长解释概念、提供代码示例和最佳实践。 role_definition: | 你是一名资深的全栈开发工程师专注于Web后端和数据处理技术栈。你的回答风格严谨、准确偏好使用代码片段和列表来阐明观点。对于不确定的知识你会明确告知用户你的局限性并建议可靠的官方文档来源。 core_objectives: - 准确理解用户关于特定编程语言如Python、JavaScript、框架如Django、React或概念如REST API、数据库索引的问题。 - 提供清晰的概念解释并辅以简短、可运行的代码示例。 - 当涉及版本差异或最佳实践时明确指出并说明理由。 - 引导用户查阅官方文档获取最权威和最新的信息。 constraints: - 不回答与编程无关的问题如娱乐、生活建议等。 - 不生成完整的、可用于生产环境的大型项目代码只提供说明性的片段。 - 不提供任何涉及系统安全漏洞利用、恶意软件编写或违反法律法规的代码或建议。 - 对于过于模糊或宽泛的问题应请求用户提供更多上下文或具体化问题。 output_format: type: structured_markdown required_sections: - 概念解释 - 代码示例如适用 - 相关资源链接如适用 - 注意事项这个YAML文件完整地定义了一个Skill。在实际框架中如Dify的“模型配置”、或自定义的Agent系统这些信息会被加载并作为系统提示词的一部分注入给LLM。3.3 第二步设计Prompt模板prompt_template.pyPrompt模板需要动态组装。我们创建一个Python函数来处理。# prompt_template.py def build_tech_prompt(user_question: str, conversation_history: list None, search_results: list None) - list: 构建技术文档助手的Prompt消息列表。 返回格式符合OpenAI等API的messages格式。 system_message { role: system, content: f你正在以【{skill_definition[name]}】的身份工作。请严格遵守以下角色定义和约束 角色定义 {skill_definition[role_definition]} 核心目标 {chr(10).join([- obj for obj in skill_definition[core_objectives]])} 约束 {chr(10).join([- con for con in skill_definition[constraints]])} 输出格式要求 请务必按照以下Markdown结构组织你的回答 ### 概念解释 [你的解释] ### 代码示例如适用 [语言] [你的代码]相关资源链接如适用链接描述注意事项[注意事项1][注意事项2] }messages [system_message]添加上下文对话历史if conversation_history: messages.extend(conversation_history) # 假设history已经是正确的message格式添加上下文搜索到的相关文档RAG结果if search_results: context_content 以下是一些可能相关的参考文档片段\n for i, doc in enumerate(search_results[:3]): # 取前3条最相关的 context_content f\n**[片段{i1}]** {doc[snippet]}\n来源{doc[source]}\n messages.append({role: system, content: context_content})添加用户当前问题messages.append({role: user, content: user_question})return messages假设我们从YAML加载了skill_definitionimport yaml with open(skill_definition.yaml, r) as f: skill_definition yaml.safe_load(f)这个模板函数展示了如何动态地将Skill定义、对话历史、检索到的知识RAG和当前问题组合成一个完整的Prompt。这是LLM文件编写的核心环节。 **3.4 第三步配置一个简单的Tooltool_search.py** 让我们为助手配置一个“搜索网络文档”的工具。这里我们模拟一个搜索函数。 python # tool_search.py import requests def search_web_docs(query: str, max_results: int 5) - list: 模拟搜索工具根据查询词返回相关的文档片段。 在实际应用中这里可能连接Elasticsearch、向量数据库或第三方API如Serper.dev。 # 这里只是一个模拟示例。实际应用中你需要替换为真实的搜索逻辑。 print(f[Tool Call] 正在搜索: {query}) # 模拟API调用和结果解析 # response requests.get(fhttps://api.your-search-service.com/search?q{query}) # results parse_response(response) # 模拟返回数据 mock_results [ { snippet: Python的asyncio库用于编写并发代码使用async/await语法。它特别适用于I/O密集型任务。, source: Python官方文档 - asyncio章节, relevance_score: 0.95 }, { snippet: 在async函数中使用await来挂起当前协程等待另一个协程完成。, source: Real Python教程 - Async IO in Python, relevance_score: 0.87 } ] # 根据相关性分数排序并返回指定数量 sorted_results sorted(mock_results, keylambda x: x[relevance_score], reverseTrue) return sorted_results[:max_results] # Tool的配置描述这个描述会被用于让LLM理解何时调用此工具。 TOOL_DESCRIPTION_FOR_LLM { name: search_web_docs, description: 当用户的问题涉及最新的技术动态、特定的库/框架的详细用法或者你需要验证某个不确定的信息时使用此工具搜索互联网上的技术文档和教程。, parameters: { type: object, properties: { query: { type: string, description: 用于搜索的关键词应简洁、精准例如‘Python asyncio event loop详解’ }, max_results: { type: integer, description: 希望返回的最大结果数量默认为5, default: 5 } }, required: [query] } }3.5 第四步组装与调用main.py最后我们将所有部分组装起来形成一个简单的运行流程。# main.py import json from prompt_template import build_tech_prompt from tool_search import search_web_docs, TOOL_DESCRIPTION_FOR_LLM # 模拟调用LLM API的函数 def call_llm_api(messages, toolsNone): # 此处应替换为真实的API调用如OpenAI的ChatCompletion # 这里仅作流程演示 print( 发送给LLM的请求 ) print(json.dumps({messages: messages, tools: tools}, indent2, ensure_asciiFalse)) print(\n) # 假设LLM返回了一个包含工具调用的响应 mock_response { role: assistant, content: None, tool_calls: [{ id: call_123, type: function, function: { name: search_web_docs, arguments: json.dumps({query: Python asyncio 入门教程, max_results: 3}) } }] } return mock_response def main(): user_question 请给我解释一下Python中的asyncio是怎么工作的最好有例子。 conversation_history [] # 假设是新对话 # 1. 首先构建不包含搜索结果的Prompt让LLM判断是否需要搜索 initial_messages build_tech_prompt(user_question, conversation_history) # 将工具描述也传给LLM让它知道可以调用什么 llm_response call_llm_api(initial_messages, tools[TOOL_DESCRIPTION_FOR_LLM]) # 2. 处理LLM的工具调用请求 if llm_response.get(tool_calls): for tool_call in llm_response[tool_calls]: if tool_call[function][name] search_web_docs: # 解析参数 args json.loads(tool_call[function][arguments]) # 执行工具 search_results search_web_docs(**args) print(f[系统] 工具调用返回结果: {search_results}\n) # 3. 将工具执行结果作为上下文再次调用LLM生成最终答案 final_messages build_tech_prompt(user_question, conversation_history, search_results) # 这次调用通常不需要再传tools或者限制其再次调用 final_llm_response call_llm_api(final_messages) # 处理final_llm_response中的content即为最终答案 print([助手] 最终回答基于搜索:) # 这里应打印 final_llm_response[content] print(此处模拟显示整合了搜索结果的详细解释...) else: # 如果LLM没有调用工具直接使用其返回的content print([助手] 回答:) print(llm_response.get(content, 无内容)) if __name__ __main__: main()这个简单的流程演示了LLM文件编写中几个核心文件的协作定义文件YAML、模板文件Python函数、工具文件Python函数描述、以及主流程控制文件。在实际的框架中这些部分会被更优雅地封装和管理但底层逻辑是相通的。4. 精通之路高级技巧与架构设计当你掌握了基础编写能力后要构建稳定、高效、可维护的生产级应用就需要关注以下高级主题。4.1 提示词工程进阶超越基础模板思维链Chain-of-Thought, CoT与少样本提示Few-Shot在Prompt模板中不仅要求输出结果更要求AI展示推理过程。例如“请一步步思考用户的问题属于哪个技术范畴核心概念是什么常见的误解有哪些最后给出答案。”同时在模板中提供1-3个高质量的输入输出示例Few-Shot能极大地提升AI在复杂任务上的表现。输出结构化与格式化强制要求AI以JSON、XML或特定Markdown格式输出这对于后续的程序化处理至关重要。在Prompt中明确给出Schema示例。例如“请输出一个JSON对象包含explanation字符串、code_example字符串可为null、confidence浮点数三个字段。”动态上下文管理如何高效利用有限的上下文窗口这需要设计策略摘要历史当对话历史过长时不是简单截断而是让AI或一个轻量模型对之前的历史进行摘要将摘要作为新的上下文。关键信息提取从长文档或多轮对话中提取出与本轮问题最相关的实体、事实、决策点而非注入全文。分层注入将上下文分为“系统指令层”长期不变、“会话记忆层”摘要或关键点、“本次查询相关层”检索结果优先级依次降低。4.2 工具调用Function Calling的稳定性设计工具调用是Agent能力的核心也是最容易出错的地方。工具描述的优化LLM根据描述决定是否及如何调用工具。描述要精准、无歧义、说明使用场景。糟糕的描述“查询数据”。好的描述“根据提供的用户ID从‘用户订单’数据库表中查询该用户最近3个月内所有状态为‘已发货’或‘配送中’的订单记录返回订单号、商品名称、发货时间和物流单号。”参数校验与兜底在Tool的执行函数内部必须对LLM传来的参数进行严格校验类型、范围、必填。即使LLM理解了描述也可能生成格式稍偏的参数。同时设计友好的错误信息返回给LLM让它能修正后重试。并行与串行调用对于多个独立工具可以设计成并行调用以提升效率。但对于有依赖关系的工具如先登录获取token再用token查询必须设计成串行并在Prompt中明确告知LLM执行顺序。工具调用的超时与重试网络请求可能失败。必须为每个工具调用设置合理的超时时间并设计重试逻辑如最多3次指数退避。4.3 与RAG检索增强生成的深度集成对于需要大量外部知识的场景RAG是必选项。LLM文件需要定义如何与RAG系统交互。检索指令的编写在Prompt模板中明确告诉AI“当你需要查询最新信息或内部文档时可以使用search_knowledge_base工具”。同时要优化用户的原始问题将其转化为更适合检索的查询词Query。有时这需要先让LLM对用户问题进行“查询意图解析”。检索结果的排序与过滤RAG系统可能返回多条相关文档。需要在Prompt模板中设计如何呈现这些结果按相关性排序、去重、甚至让AI先对结果进行初步筛选和总结再基于最精华的部分生成最终答案。引用与溯源在最终输出中要求AI注明答案的参考来源例如“根据[2023年产品手册第5页]...”。这不仅能增加可信度也方便用户追溯和验证。4.4 复杂工作流Workflow与状态管理对于涉及多步骤、多分支判断的任务需要设计工作流。使用可视化工具像Dify、LangFlow这样的平台提供了低代码的Workflow设计界面你可以通过拖拽节点LLM节点、工具节点、判断节点、代码节点来编排流程。这对于业务逻辑清晰的任务非常高效。使用编程框架对于更复杂、需要定制逻辑的流程LangGraph是一个强大的选择。它允许你用图Graph来定义Agent的工作流节点是状态State或任务边是条件转移。你可以清晰地定义“如果工具A调用成功则进入节点B如果失败则进入错误处理节点C”。状态State设计在整个Workflow中需要维护一个共享的状态对象State。这个State包含了当前输入、中间结果如工具调用结果、对话历史、下一步决策等信息。良好的State设计是Workflow清晰和可调试的关键。5. 避坑指南与性能优化5.1 常见问题与排查清单AI不按格式输出检查点在Prompt中格式指令是否足够清晰、强硬是否提供了输出示例Few-Shot解决强化指令如“你必须严格按照以下JSON格式输出不要有任何其他解释文字。”并在后处理代码中添加格式校验和重试逻辑。工具调用不准确或不被调用检查点工具描述是否清晰无歧义输入参数的Schema定义是否准确用户问题是否足够具体以触发工具调用解决优化工具描述增加使用场景和示例。在Prompt中明确鼓励AI在不确定时使用工具查询。检查LLM返回的tool_calls字段看其生成的参数是否符合预期。上下文溢出Token超限检查点注入的对话历史、检索内容是否过长是否包含了不必要的信息解决实施上下文管理策略见4.1。对于长文档使用更智能的检索方式如句子窗口检索、自动摘要而非全文注入。考虑使用支持更长上下文的模型。响应速度慢检查点是LLM本身生成慢还是工具调用如网络请求、数据库查询慢或者是工作流中串行步骤太多解决为工具调用设置超时和缓存。分析工作流将可以并行的步骤改为并行。考虑对LLM的响应进行流式输出Streaming提升用户体验。输出结果不稳定同样输入不同输出检查点是否设置了temperature温度参数温度越高随机性越大。解决对于需要确定性输出的生产任务如数据提取、代码生成将temperature设置为0或接近0如0.1。同时确保Prompt指令具有足够的确定性。5.2 成本与性能优化模型选型不是所有任务都需要GPT-4。对于简单的分类、提取、格式化任务使用更小、更快的模型如GPT-3.5-Turbo、Claude Haiku可以大幅降低成本、提升速度。将复杂任务拆解让大模型做规划Planning小模型做执行Execution。缓存策略对于频繁出现的、结果固定的查询如“公司的退货政策是什么”可以将LLM的完整响应缓存起来下次直接返回避免重复计算。也可以缓存工具调用的结果。异步处理对于不要求实时响应的任务如批量处理文档、生成报告采用异步队列处理避免阻塞主线程并可以更好地利用资源。监控与评估建立监控体系记录每次调用的耗时、Token使用量、费用、工具调用成功率、用户反馈如有。定期评估不同Prompt版本、不同模型的效果持续迭代优化。6. 工具链与生态选择“工欲善其事必先利其器”。选择合适的框架和平台能事半功倍。轻量级/快速原型如果你需要快速验证一个想法或者项目比较简单Dify和LangChain是很好的起点。Dify提供了可视化的Prompt编排、RAG构建和工作流设计几乎不需要写代码。LangChain提供了丰富的组件和链Chain编程灵活。复杂Agent与状态机如果你的应用涉及多Agent协作、复杂的决策循环和状态管理LangGraph是目前最强大的框架之一。它基于有向图来定义工作流非常适合构建具备规划、执行、反思能力的智能体。生产级部署与运维如果你关注高可用、可观测性、安全性和规模化需要考虑更企业级的解决方案如Haystack或基于FastAPI自行构建微服务并集成完善的日志、监控、认证体系。提示词版本管理与测试使用PromptHub、Weights Biases或Arize AI等工具来管理不同版本的Prompt模板进行A/B测试分析不同Prompt对输出质量和成本的影响。终极心得LLM文件编写本质上是“人机协同”的界面设计。它要求开发者既要有对业务逻辑的深刻理解又要有将非结构化需求转化为结构化指令的能力。这个过程是迭代的没有一劳永逸的“银弹”Prompt。最好的方法就是“构建-测量-学习”循环快速构建一个可运行的版本投入真实场景测试收集反馈分析失败案例然后回头修改你的Skill定义、Prompt模板或工具配置。随着你对模型“习性”的把握越来越深你编写的“说明书”就会越来越高效最终打造出真正智能、可靠的AI应用。 
长河君 · 2026/8/7 6:46:55 · 阅读 1.2k LLM文件编写：从Prompt工程到Agent工作流的实战指南
1. 项目概述为什么“LLM文件编写”是当下最值得投入的技能如果你最近在关注AI应用开发尤其是大语言模型LLM的落地那么“LLM文件编写”这个词组一定高频出现在你的视野里。它听起来可能有点技术化甚至有些枯燥但我想告诉你这恰恰是连接创意想法与可运行AI应用之间最核心、最实用、也最容易被忽视的桥梁。简单来说LLM文件编写就是一套“告诉AI如何思考和行动”的标准化说明书。它不是简单的聊天也不是写几行代码调用API而是通过结构化的文档定义LLM的角色Skill、思考流程Prompt模板、可用工具Tool配置以及知识边界RAG/知识库。为什么说它从“入门”到“精通”的路径如此重要因为当前的LLM应用开发正从早期的“炫技式对话”走向深度的“生产级集成”。一个能聊天的AI助理和一個能自动处理工单、分析报表、生成合规文档的AI员工其核心区别就在于后者拥有一套精心设计的“操作手册”——也就是我们所说的LLM文件。无论是使用LangChain、Dify、FastAPI自建框架还是直接调用Claude、GPT的API最终决定应用智能上限和稳定性的往往不是模型本身而是开发者编写的这些配置文件、提示词模板和工具定义。我见过太多项目初期模型选型很酷架构图画得很漂亮但一进入实际开发团队就在“如何让AI准确理解业务逻辑”、“如何让AI稳定调用外部工具”、“如何管理复杂的多轮对话状态”这些问题上反复踩坑。其根源大多是对LLM文件编写缺乏系统性的认知和实践。掌握这项技能意味着你能将模糊的需求转化为AI可执行的精确指令能设计出高效、可靠且易于维护的AI工作流Workflow能真正释放LLM在垂直领域的潜力。接下来我将结合我踩过的坑和总结的经验为你拆解从入门到精通的全路径。2. 核心概念拆解Skill, Prompt, Tool, Agent 到底是什么关系刚接触时这些术语容易让人混淆。我们可以把它们想象成一个AI特工Agent的装备和训练手册。2.1 Skill技能/角色定义AI的“人设”与核心能力集Skill是LLM文件的顶层设计它定义了AI在特定任务中的身份、目标和能力边界。这不是一句“你是一个有帮助的助手”那么简单。一个精良的Skill定义通常包含身份与背景明确、具体的角色。例如“你是一名拥有10年经验的跨境电商客服专家擅长处理物流纠纷和退款申请语气专业且富有同理心。”核心职责与目标清晰的任务范围。例如“你的核心目标是安抚用户情绪快速定位物流问题节点并根据公司政策提供解决方案选项最终目标是提升客户满意度避免升级投诉。”约束与边界防止AI“胡说八道”或越界。例如“你只能处理订单创建后90天内的物流查询。对于产品质量问题应引导用户联系质检部门。严禁对用户做出无法兑现的承诺如‘明天一定送到’。”输出格式规范确保结果能被下游系统处理。例如“你的回复必须是一个JSON对象包含problem_type问题分类、suggested_solutions解决方案数组和next_step建议用户操作三个字段。”实操心得定义Skill时最忌讳宽泛。越具体AI的表现越稳定。我通常会为同一个应用设计多个细分的Skill比如“售前咨询Skill”、“售后工单Skill”、“数据查询Skill”而不是试图用一个“万能助理Skill”解决所有问题。2.2 Prompt模板提示词模板AI的“思考框架”与上下文管理器如果说Skill是战略Prompt模板就是战术脚本。它是在Skill框架下针对具体对话轮次或任务步骤设计的结构化输入。一个高效的Prompt模板远不止是用户问题的前缀。它通常由以下几部分组成系统指令System Message重申或细化当前步骤的Skill要求。这部分通常固定放在对话开头。上下文Context动态注入的信息如本次对话的历史记录、从知识库检索到的相关文档、从数据库查询到的用户订单数据等。这是实现“记忆”和“精准”的关键。用户输入User Input当前用户的问题或指令。输出指示Output Indicator明确告诉AI以何种形式思考和组织答案。例如“请按以下步骤分析1. 识别用户情绪2. 提取关键实体订单号、问题类型3. 匹配知识库条款4. 生成回复。”2.3 Tool配置工具调用配置AI的“手脚”与外部世界连接器LLM本身是“大脑”它需要“手脚”Tools来执行具体操作比如查询数据库、调用API、发送邮件、生成图表。Tool配置就是定义这些手脚如何工作。一个Tool配置通常包括工具名称与描述用自然语言清晰描述工具的功能这本身就是给LLM的“使用说明书”。例如“query_order_status根据用户提供的订单号从公司订单数据库中查询最新的物流状态和预计送达时间。”输入参数模式Schema严格定义工具需要的输入参数名称、类型、是否必填、描述。这通常用JSON Schema定义。例如order_id字符串必填。执行函数/API端点工具被调用时实际执行的代码函数或HTTP请求。授权与错误处理工具调用所需的认证信息如API Key以及调用失败时的回退策略。2.4 Agent与WorkflowSkill、Prompt、Tool的编排与调度当单个Skill和Tool无法完成复杂任务时就需要Agent和Workflow。你可以把Agent看作一个具备自主规划能力的“经理”它根据目标决定调用哪个Skill使用哪些Tool并管理整个执行流程。基于LLM的Agent例如使用LangGraph或AutoGen框架让一个“规划Agent”先拆解任务然后调用不同的“执行Agent”每个对应一个Skill和Tools。基于规则的Workflow例如在Dify、LangChain中可视化的流程设计器。你可以拖拽节点定义清晰的执行路径先触发Skill A然后调用Tool B查询数据再将结果注入Prompt模板C最后生成输出。这种方式更可控适合流程固定的任务。它们的关系总结Skill定义了AI是谁、要做什么Prompt模板指导它在具体场景中如何思考Tool赋予它行动的能力而Agent/Workflow则将这一切串联起来完成从“思考”到“行动”的闭环。编写LLM文件本质上就是在精心设计这套“特工装备系统”。3. 从零开始你的第一个LLM文件编写实战理论说了这么多我们直接动手创建一个简单的“技术文档助手”Skill。我们将定义它的角色、设计一个Prompt模板并为其配置一个搜索工具。3.1 环境与工具准备我们不依赖任何重型框架以最通用的方式开始。你需要一个LLM API访问权限例如OpenAI GPT、Claude、或国内可用的主流模型API。一个代码编辑器VS Code、PyCharm等皆可。Python环境安装requests库用于调用API和工具。3.2 第一步编写Skill定义skill_definition.yaml我们采用YAML格式因为它结构清晰易于阅读和版本管理。# skill_definition.yaml name: tech_doc_assistant version: 1.0 description: 一个专注于回答编程语言和框架相关技术问题的助手。擅长解释概念、提供代码示例和最佳实践。 role_definition: | 你是一名资深的全栈开发工程师专注于Web后端和数据处理技术栈。你的回答风格严谨、准确偏好使用代码片段和列表来阐明观点。对于不确定的知识你会明确告知用户你的局限性并建议可靠的官方文档来源。 core_objectives: - 准确理解用户关于特定编程语言如Python、JavaScript、框架如Django、React或概念如REST API、数据库索引的问题。 - 提供清晰的概念解释并辅以简短、可运行的代码示例。 - 当涉及版本差异或最佳实践时明确指出并说明理由。 - 引导用户查阅官方文档获取最权威和最新的信息。 constraints: - 不回答与编程无关的问题如娱乐、生活建议等。 - 不生成完整的、可用于生产环境的大型项目代码只提供说明性的片段。 - 不提供任何涉及系统安全漏洞利用、恶意软件编写或违反法律法规的代码或建议。 - 对于过于模糊或宽泛的问题应请求用户提供更多上下文或具体化问题。 output_format: type: structured_markdown required_sections: - 概念解释 - 代码示例如适用 - 相关资源链接如适用 - 注意事项这个YAML文件完整地定义了一个Skill。在实际框架中如Dify的“模型配置”、或自定义的Agent系统这些信息会被加载并作为系统提示词的一部分注入给LLM。3.3 第二步设计Prompt模板prompt_template.pyPrompt模板需要动态组装。我们创建一个Python函数来处理。# prompt_template.py def build_tech_prompt(user_question: str, conversation_history: list None, search_results: list None) - list: 构建技术文档助手的Prompt消息列表。 返回格式符合OpenAI等API的messages格式。 system_message { role: system, content: f你正在以【{skill_definition[name]}】的身份工作。请严格遵守以下角色定义和约束 角色定义 {skill_definition[role_definition]} 核心目标 {chr(10).join([- obj for obj in skill_definition[core_objectives]])} 约束 {chr(10).join([- con for con in skill_definition[constraints]])} 输出格式要求 请务必按照以下Markdown结构组织你的回答 ### 概念解释 [你的解释] ### 代码示例如适用 [语言] [你的代码]相关资源链接如适用链接描述注意事项[注意事项1][注意事项2] }messages [system_message]添加上下文对话历史if conversation_history: messages.extend(conversation_history) # 假设history已经是正确的message格式添加上下文搜索到的相关文档RAG结果if search_results: context_content 以下是一些可能相关的参考文档片段\n for i, doc in enumerate(search_results[:3]): # 取前3条最相关的 context_content f\n**[片段{i1}]** {doc[snippet]}\n来源{doc[source]}\n messages.append({role: system, content: context_content})添加用户当前问题messages.append({role: user, content: user_question})return messages假设我们从YAML加载了skill_definitionimport yaml with open(skill_definition.yaml, r) as f: skill_definition yaml.safe_load(f)这个模板函数展示了如何动态地将Skill定义、对话历史、检索到的知识RAG和当前问题组合成一个完整的Prompt。这是LLM文件编写的核心环节。 **3.4 第三步配置一个简单的Tooltool_search.py** 让我们为助手配置一个“搜索网络文档”的工具。这里我们模拟一个搜索函数。 python # tool_search.py import requests def search_web_docs(query: str, max_results: int 5) - list: 模拟搜索工具根据查询词返回相关的文档片段。 在实际应用中这里可能连接Elasticsearch、向量数据库或第三方API如Serper.dev。 # 这里只是一个模拟示例。实际应用中你需要替换为真实的搜索逻辑。 print(f[Tool Call] 正在搜索: {query}) # 模拟API调用和结果解析 # response requests.get(fhttps://api.your-search-service.com/search?q{query}) # results parse_response(response) # 模拟返回数据 mock_results [ { snippet: Python的asyncio库用于编写并发代码使用async/await语法。它特别适用于I/O密集型任务。, source: Python官方文档 - asyncio章节, relevance_score: 0.95 }, { snippet: 在async函数中使用await来挂起当前协程等待另一个协程完成。, source: Real Python教程 - Async IO in Python, relevance_score: 0.87 } ] # 根据相关性分数排序并返回指定数量 sorted_results sorted(mock_results, keylambda x: x[relevance_score], reverseTrue) return sorted_results[:max_results] # Tool的配置描述这个描述会被用于让LLM理解何时调用此工具。 TOOL_DESCRIPTION_FOR_LLM { name: search_web_docs, description: 当用户的问题涉及最新的技术动态、特定的库/框架的详细用法或者你需要验证某个不确定的信息时使用此工具搜索互联网上的技术文档和教程。, parameters: { type: object, properties: { query: { type: string, description: 用于搜索的关键词应简洁、精准例如‘Python asyncio event loop详解’ }, max_results: { type: integer, description: 希望返回的最大结果数量默认为5, default: 5 } }, required: [query] } }3.5 第四步组装与调用main.py最后我们将所有部分组装起来形成一个简单的运行流程。# main.py import json from prompt_template import build_tech_prompt from tool_search import search_web_docs, TOOL_DESCRIPTION_FOR_LLM # 模拟调用LLM API的函数 def call_llm_api(messages, toolsNone): # 此处应替换为真实的API调用如OpenAI的ChatCompletion # 这里仅作流程演示 print( 发送给LLM的请求 ) print(json.dumps({messages: messages, tools: tools}, indent2, ensure_asciiFalse)) print(\n) # 假设LLM返回了一个包含工具调用的响应 mock_response { role: assistant, content: None, tool_calls: [{ id: call_123, type: function, function: { name: search_web_docs, arguments: json.dumps({query: Python asyncio 入门教程, max_results: 3}) } }] } return mock_response def main(): user_question 请给我解释一下Python中的asyncio是怎么工作的最好有例子。 conversation_history [] # 假设是新对话 # 1. 首先构建不包含搜索结果的Prompt让LLM判断是否需要搜索 initial_messages build_tech_prompt(user_question, conversation_history) # 将工具描述也传给LLM让它知道可以调用什么 llm_response call_llm_api(initial_messages, tools[TOOL_DESCRIPTION_FOR_LLM]) # 2. 处理LLM的工具调用请求 if llm_response.get(tool_calls): for tool_call in llm_response[tool_calls]: if tool_call[function][name] search_web_docs: # 解析参数 args json.loads(tool_call[function][arguments]) # 执行工具 search_results search_web_docs(**args) print(f[系统] 工具调用返回结果: {search_results}\n) # 3. 将工具执行结果作为上下文再次调用LLM生成最终答案 final_messages build_tech_prompt(user_question, conversation_history, search_results) # 这次调用通常不需要再传tools或者限制其再次调用 final_llm_response call_llm_api(final_messages) # 处理final_llm_response中的content即为最终答案 print([助手] 最终回答基于搜索:) # 这里应打印 final_llm_response[content] print(此处模拟显示整合了搜索结果的详细解释...) else: # 如果LLM没有调用工具直接使用其返回的content print([助手] 回答:) print(llm_response.get(content, 无内容)) if __name__ __main__: main()这个简单的流程演示了LLM文件编写中几个核心文件的协作定义文件YAML、模板文件Python函数、工具文件Python函数描述、以及主流程控制文件。在实际的框架中这些部分会被更优雅地封装和管理但底层逻辑是相通的。4. 精通之路高级技巧与架构设计当你掌握了基础编写能力后要构建稳定、高效、可维护的生产级应用就需要关注以下高级主题。4.1 提示词工程进阶超越基础模板思维链Chain-of-Thought, CoT与少样本提示Few-Shot在Prompt模板中不仅要求输出结果更要求AI展示推理过程。例如“请一步步思考用户的问题属于哪个技术范畴核心概念是什么常见的误解有哪些最后给出答案。”同时在模板中提供1-3个高质量的输入输出示例Few-Shot能极大地提升AI在复杂任务上的表现。输出结构化与格式化强制要求AI以JSON、XML或特定Markdown格式输出这对于后续的程序化处理至关重要。在Prompt中明确给出Schema示例。例如“请输出一个JSON对象包含explanation字符串、code_example字符串可为null、confidence浮点数三个字段。”动态上下文管理如何高效利用有限的上下文窗口这需要设计策略摘要历史当对话历史过长时不是简单截断而是让AI或一个轻量模型对之前的历史进行摘要将摘要作为新的上下文。关键信息提取从长文档或多轮对话中提取出与本轮问题最相关的实体、事实、决策点而非注入全文。分层注入将上下文分为“系统指令层”长期不变、“会话记忆层”摘要或关键点、“本次查询相关层”检索结果优先级依次降低。4.2 工具调用Function Calling的稳定性设计工具调用是Agent能力的核心也是最容易出错的地方。工具描述的优化LLM根据描述决定是否及如何调用工具。描述要精准、无歧义、说明使用场景。糟糕的描述“查询数据”。好的描述“根据提供的用户ID从‘用户订单’数据库表中查询该用户最近3个月内所有状态为‘已发货’或‘配送中’的订单记录返回订单号、商品名称、发货时间和物流单号。”参数校验与兜底在Tool的执行函数内部必须对LLM传来的参数进行严格校验类型、范围、必填。即使LLM理解了描述也可能生成格式稍偏的参数。同时设计友好的错误信息返回给LLM让它能修正后重试。并行与串行调用对于多个独立工具可以设计成并行调用以提升效率。但对于有依赖关系的工具如先登录获取token再用token查询必须设计成串行并在Prompt中明确告知LLM执行顺序。工具调用的超时与重试网络请求可能失败。必须为每个工具调用设置合理的超时时间并设计重试逻辑如最多3次指数退避。4.3 与RAG检索增强生成的深度集成对于需要大量外部知识的场景RAG是必选项。LLM文件需要定义如何与RAG系统交互。检索指令的编写在Prompt模板中明确告诉AI“当你需要查询最新信息或内部文档时可以使用search_knowledge_base工具”。同时要优化用户的原始问题将其转化为更适合检索的查询词Query。有时这需要先让LLM对用户问题进行“查询意图解析”。检索结果的排序与过滤RAG系统可能返回多条相关文档。需要在Prompt模板中设计如何呈现这些结果按相关性排序、去重、甚至让AI先对结果进行初步筛选和总结再基于最精华的部分生成最终答案。引用与溯源在最终输出中要求AI注明答案的参考来源例如“根据[2023年产品手册第5页]...”。这不仅能增加可信度也方便用户追溯和验证。4.4 复杂工作流Workflow与状态管理对于涉及多步骤、多分支判断的任务需要设计工作流。使用可视化工具像Dify、LangFlow这样的平台提供了低代码的Workflow设计界面你可以通过拖拽节点LLM节点、工具节点、判断节点、代码节点来编排流程。这对于业务逻辑清晰的任务非常高效。使用编程框架对于更复杂、需要定制逻辑的流程LangGraph是一个强大的选择。它允许你用图Graph来定义Agent的工作流节点是状态State或任务边是条件转移。你可以清晰地定义“如果工具A调用成功则进入节点B如果失败则进入错误处理节点C”。状态State设计在整个Workflow中需要维护一个共享的状态对象State。这个State包含了当前输入、中间结果如工具调用结果、对话历史、下一步决策等信息。良好的State设计是Workflow清晰和可调试的关键。5. 避坑指南与性能优化5.1 常见问题与排查清单AI不按格式输出检查点在Prompt中格式指令是否足够清晰、强硬是否提供了输出示例Few-Shot解决强化指令如“你必须严格按照以下JSON格式输出不要有任何其他解释文字。”并在后处理代码中添加格式校验和重试逻辑。工具调用不准确或不被调用检查点工具描述是否清晰无歧义输入参数的Schema定义是否准确用户问题是否足够具体以触发工具调用解决优化工具描述增加使用场景和示例。在Prompt中明确鼓励AI在不确定时使用工具查询。检查LLM返回的tool_calls字段看其生成的参数是否符合预期。上下文溢出Token超限检查点注入的对话历史、检索内容是否过长是否包含了不必要的信息解决实施上下文管理策略见4.1。对于长文档使用更智能的检索方式如句子窗口检索、自动摘要而非全文注入。考虑使用支持更长上下文的模型。响应速度慢检查点是LLM本身生成慢还是工具调用如网络请求、数据库查询慢或者是工作流中串行步骤太多解决为工具调用设置超时和缓存。分析工作流将可以并行的步骤改为并行。考虑对LLM的响应进行流式输出Streaming提升用户体验。输出结果不稳定同样输入不同输出检查点是否设置了temperature温度参数温度越高随机性越大。解决对于需要确定性输出的生产任务如数据提取、代码生成将temperature设置为0或接近0如0.1。同时确保Prompt指令具有足够的确定性。5.2 成本与性能优化模型选型不是所有任务都需要GPT-4。对于简单的分类、提取、格式化任务使用更小、更快的模型如GPT-3.5-Turbo、Claude Haiku可以大幅降低成本、提升速度。将复杂任务拆解让大模型做规划Planning小模型做执行Execution。缓存策略对于频繁出现的、结果固定的查询如“公司的退货政策是什么”可以将LLM的完整响应缓存起来下次直接返回避免重复计算。也可以缓存工具调用的结果。异步处理对于不要求实时响应的任务如批量处理文档、生成报告采用异步队列处理避免阻塞主线程并可以更好地利用资源。监控与评估建立监控体系记录每次调用的耗时、Token使用量、费用、工具调用成功率、用户反馈如有。定期评估不同Prompt版本、不同模型的效果持续迭代优化。6. 工具链与生态选择“工欲善其事必先利其器”。选择合适的框架和平台能事半功倍。轻量级/快速原型如果你需要快速验证一个想法或者项目比较简单Dify和LangChain是很好的起点。Dify提供了可视化的Prompt编排、RAG构建和工作流设计几乎不需要写代码。LangChain提供了丰富的组件和链Chain编程灵活。复杂Agent与状态机如果你的应用涉及多Agent协作、复杂的决策循环和状态管理LangGraph是目前最强大的框架之一。它基于有向图来定义工作流非常适合构建具备规划、执行、反思能力的智能体。生产级部署与运维如果你关注高可用、可观测性、安全性和规模化需要考虑更企业级的解决方案如Haystack或基于FastAPI自行构建微服务并集成完善的日志、监控、认证体系。提示词版本管理与测试使用PromptHub、Weights Biases或Arize AI等工具来管理不同版本的Prompt模板进行A/B测试分析不同Prompt对输出质量和成本的影响。终极心得LLM文件编写本质上是“人机协同”的界面设计。它要求开发者既要有对业务逻辑的深刻理解又要有将非结构化需求转化为结构化指令的能力。这个过程是迭代的没有一劳永逸的“银弹”Prompt。最好的方法就是“构建-测量-学习”循环快速构建一个可运行的版本投入真实场景测试收集反馈分析失败案例然后回头修改你的Skill定义、Prompt模板或工具配置。随着你对模型“习性”的把握越来越深你编写的“说明书”就会越来越高效最终打造出真正智能、可靠的AI应用。