角色提示Role Prompting实战用 Instructor 为 LLM 分配角色提升零样本结构化输出质量【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor在零样本场景下如何仅靠提示就让模型在开放式任务上表现得更出色角色提示Role Prompting又称人格提示 Persona Prompting给出了一个成本最低、见效最快的答案为模型分配一个明确角色。本文以 docs/prompting/zero_shot/role_prompting.md 为骨架结合 Instructor 仓库的源码与文档完整演示如何在结构化输出管线中使用角色提示并延伸到角色选择、多角色协作与 Schema 设计等进阶实践。读完本文你将掌握一套角色 Pydantic 响应模型的组合拳能直接用于诗歌创作、专家问答、内容风格化等各类生成与抽取任务。什么是角色提示给模型一个人设角色提示的核心思想很简单在提示词中为模型分配一个角色让模型以该角色的身份和视角来回应任务。这个角色可以有两种粒度任务特定角色specific to the queryYou are a talented writer. Write me a poem.你是一位才华横溢的作家为我写一首诗。通用/社交角色general/socialYou are a helpful AI assistant. Write me a poem.你是一位乐于助人的 AI 助手为我写一首诗。两种角色的差异在于约束强度与适用范围任务特定角色直接把模型的立场、知识背景和语言风格锁定在任务相关的专家人设上通用角色则只提供最基础的行为约束。实践经验表明在开放式任务中一个定义良好的专家角色往往能带来更聚焦、更高质量的生成结果这正是角色提示被归类为零样本Zero-Shot提示技术的原因——它不需要任何示例只通过一句角色声明就能改变模型的行为分布。在 docs/prompting/index.md 的技术选型表中角色提示被明确列为生成创意内容Generate creative content场景的推荐技术与情感语言Emotional Language、风格定义Style Definition并列同时它也适用于需要专家知识、专业化视角Expert knowledge, specialized perspectives的任务。当你的目标是提升准确率时官方建议转向思维链、自验证等推理类技术而当目标是创意生成或专业视角输出时角色提示是第一顺位。零样本家族中的位置角色提示属于 Instructor 提示技术图谱中零样本Zero-Shot分支的一员。该分支中的所有技术都以不给示例、只改提示为前提包括技术作用典型场景角色提示Role Prompting为模型分配特定角色专家知识、专业化视角情感语言Emotional Language在提示中注入情感语气创意写作、共情回复风格定义Style Definition明确指定写作风格特定语气/格式的内容提示精炼Prompt Refinement自动优化提示词结果的迭代改进视角模拟Perspective Simulation让模型采纳不同视角多利益相关方分析与同为零样本技术的 风格提示Style Prompting 相比角色提示更侧重身份而风格提示更侧重输出约束写作风格、语气、情绪、体裁。二者可以叠加使用先用角色锁定身份再用风格约束输出形式从而把开放式任务一步步收窄到可控范围。用 Instructor 实现角色提示完整可运行示例原文档给出了一个将角色提示与结构化输出结合的最小实现核心模式是把角色声明拼进 system 消息同时用 Pydantic 模型约束返回结构。完整代码如下import openai import instructor from pydantic import BaseModel client instructor.from_provider(openai/gpt-5-nano) class Response(BaseModel): poem: str def role_prompting(query, role): return client.create( modelgpt-4o, response_modelResponse, messages[ { role: system, content: f{role} {query}, }, ], ) if __name__ __main__: query Write me a short poem about coffee. role You are a renowned poet. response role_prompting(query, role) print(response.poem) In the mornings gentle light, A brew of warmth, dark and bright. Awakening dreams, so sweet, In every sip, the day we greet. Through the steam, stories spin, A liquid muse, caffeine within. Moments pause, thoughts unfold, In coffees embrace, we find our gold. 这段代码的关键点在于client.create的调用方式instructor.from_provider(openai/gpt-5-nano)用一行代码创建统一接口的 Instructor 客户端详见下文源码分析response_modelResponse声明响应结构——模型输出会被强制解析为Response实例保证poem字段存在且为字符串messages中的role: system是角色注入点角色文本与查询文本拼接后整体交给系统消息返回的response.poem是已经过 Pydantic 验证的结构化字段而非原始 JSON 文本。运行这段代码即可得到一首结构完整的咖啡主题短诗——角色声明你是一位著名的诗人renowned poet直接决定了输出的文学性。深入源码from_provider 与 create 的调用链为了让上面的示例真正可运行有必要理解 Instructor 的两个底层入口。它们位于仓库的核心实现中是全部提示技术包括角色提示落地的公共底座。from_provider统一客户端工厂instructor.from_provider的实现位于 instructor/v2/auto_client.py。其签名要求模型字符串必须符合provider/model-name格式例如openai/gpt-4o、anthropic/claude-3-5-sonnet否则会抛出ConfigurationError。函数内部会根据 provider 前缀查找对应的构建器_PROVIDER_BUILDERS自动完成底层 SDK 客户端的创建与 Instructor 的接入对 OpenAI 系含 Azure、Databricks 及各类 OpenAI 兼容网关构建器会创建openai.OpenAI/AsyncOpenAI客户端并透传api_key、base_url、timeout、max_retries、organization、default_headers等参数对 Anthropic会自动补齐max_tokens默认 4096并注入 User-Agent对 Google支持vertexaiTrue、project、location等 Vertex AI 配置。同时from_provider支持async_clientTrue返回异步客户端、cacheAutoCache(...)启用响应缓存、mode覆盖默认模式OpenAI 默认Mode.TOOLS。切换提供商只需修改一个字符串业务代码完全不变。更完整的参数说明见 docs/concepts/from_provider.md。client.create结构化输出的核心方法create的默认实现位于 instructor/v2/core/client.py签名如下def create( self, messages: str | list[ChatCompletionMessageParam] | None None, response_model: type[T] | None None, max_retries: int | Retrying 3, context: dict[str, Any] | None None, strict: bool True, token_budget: int | None None, **kwargs, ) - T | Any:其中几个参数对角色提示实战至关重要messages消息列表角色提示就注入在system消息中也可以直接传一个字符串response_modelPydantic 模型决定输出的强制结构是角色生成内容之后保证可编程消费的关键max_retries默认 3 次当模型输出无法通过 Pydantic 校验时自动重试——角色提示如果导致输出格式偏离会在此机制下被纠正strict默认True开启严格 Schema 模式token_budget可选超出预算时触发截断/重试策略。调用链最终会把response_model、messages等参数透传给底层 SDK 的create由各提供商处理器完成函数调用tool call或 JSON 模式的组装与解析。角色提示 × 结构化输出Schema 层面的配合角色提示解决了说什么、以什么身份说而 Pydantic 模型解决了以什么结构返回。两者配合时可以遵循 docs/concepts/prompting.md 中的结构工程最佳实践把角色约束渗透进 Schema1. 用 docstring 与 Field 描述强化角色指令模型的类文档字符串docstring和字段描述会随 Schema 一起发给模型因此可以在其中重申角色要求形成双重约束from pydantic import BaseModel, Field class Poem(BaseModel): You are a renowned poet. Write in vivid, literary language. title: str Field(descriptionA striking, evocative title fitting the poem) poem: str Field(descriptionThe poem itself, written from the poets perspective)2. 角色 风格叠加把角色提示与 风格提示 组合可以同时锁定身份和输出约束写作风格、语气、情绪、体裁。例如将角色设为十九世纪浪漫主义诗人风格约束设为dramatic、flowery生成的诗歌会同时在身份与文体两个维度上符合预期。3. 角色字段化便于动态切换把角色从硬编码字符串提升为函数参数或配置字段如原文档role_prompting(query, role)的做法配合response_model的枚举字段可以实现按任务类型自动选角色的工厂模式from enum import Enum from pydantic import BaseModel, Field class Persona(Enum): POET You are a renowned poet. CRITIC You are a sharp literary critic. SCIENTIST You are a meticulous scientist. class PoemReview(BaseModel): verdict: str Field(descriptionThe critics final judgment) score: int Field(descriptionScore from 1 to 10)进阶多角色协作与角色选择的系统性方法原文档在More Role Prompting一节中提示了三条研究脉络这里将其转化为可落地的实践建议系统性地选择角色来自论文RoleLLM: Benchmarking, Eliciting, and Enhancing Role-Playing Abilities of Large Language Models。其思路是先构建角色库再根据任务特征评估并挑选最合适的角色。实操上可以为不同任务族准备一组候选角色通过小规模评测挑选表现最优者避免拍脑袋选角色。评估社交角色的影响来自论文Is A Helpful Assistant the Best Role for Large Language Models? A Systematic Evaluation of Social Roles in System Prompts。该研究系统评测了系统提示中的社交角色提示我们You are a helpful assistant未必是通用最优解角色与任务匹配才是关键。多角色自我协作来自论文Unleashing the Emergent Cognitive Synergy in Large Language Models: A Task-Solving Agent through Multi-Persona Self-Collaboration。即在同一任务中让多个角色如规划者执行者评审者依次登场各司其职后聚合结果。在 Instructor 中这可以通过多次create调用串联实现先以规划者角色生成方案再以执行者角色细化最后以评审者角色校验输出。常见问题与调试建议角色文本与查询拼接的歧义f{role} {query}的写法要求角色与查询都能被模型清楚解析建议角色以句号结尾、查询独立成句避免模型把两者混淆为同一指令。角色与响应结构冲突若角色暗示了极长的自由输出如写一部小说而response_model只定义了一个短字段模型可能在结构约束下大幅压缩内容。此时应调整字段描述或拆分输出模型。验证失败导致重试max_retries默认为 3。若角色提示诱使模型输出违反 Schema 的内容例如在poem: str里输出多段 MarkdownInstructor 会自动重试若持续失败可检查角色声明是否过于模糊。切换提供商角色提示通过标准system消息传递在 OpenAI、Anthropic、Google 等from_provider支持的提供商间切换时无需改动提示代码只需修改 provider 字符串各提供商对 system 消息的底层处理略有差异行为以官方文档为准。总结角色提示是最轻量的零样本性能提升手段一句角色声明即可重塑模型的输出立场与语言风格。在 Instructor 中它与from_provider统一客户端、create结构化输出和 Pydantic 响应模型天然衔接既能用于开放式创意生成也能叠加 Field 描述、风格约束和多角色协作形成系统化的提示工程方案。相关延伸阅读可回到本仓库的 提示技术总览以及 角色提示原始文档 中引用的 RoleLLM、社交角色评测与多角色自我协作三篇论文。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
角色提示（Role Prompting）实战：用 Instructor 为 LLM 分配角色，提升零样本结构化输出质量
角色提示Role Prompting实战用 Instructor 为 LLM 分配角色提升零样本结构化输出质量【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor在零样本场景下如何仅靠提示就让模型在开放式任务上表现得更出色角色提示Role Prompting又称人格提示 Persona Prompting给出了一个成本最低、见效最快的答案为模型分配一个明确角色。本文以 docs/prompting/zero_shot/role_prompting.md 为骨架结合 Instructor 仓库的源码与文档完整演示如何在结构化输出管线中使用角色提示并延伸到角色选择、多角色协作与 Schema 设计等进阶实践。读完本文你将掌握一套角色 Pydantic 响应模型的组合拳能直接用于诗歌创作、专家问答、内容风格化等各类生成与抽取任务。什么是角色提示给模型一个人设角色提示的核心思想很简单在提示词中为模型分配一个角色让模型以该角色的身份和视角来回应任务。这个角色可以有两种粒度任务特定角色specific to the queryYou are a talented writer. Write me a poem.你是一位才华横溢的作家为我写一首诗。通用/社交角色general/socialYou are a helpful AI assistant. Write me a poem.你是一位乐于助人的 AI 助手为我写一首诗。两种角色的差异在于约束强度与适用范围任务特定角色直接把模型的立场、知识背景和语言风格锁定在任务相关的专家人设上通用角色则只提供最基础的行为约束。实践经验表明在开放式任务中一个定义良好的专家角色往往能带来更聚焦、更高质量的生成结果这正是角色提示被归类为零样本Zero-Shot提示技术的原因——它不需要任何示例只通过一句角色声明就能改变模型的行为分布。在 docs/prompting/index.md 的技术选型表中角色提示被明确列为生成创意内容Generate creative content场景的推荐技术与情感语言Emotional Language、风格定义Style Definition并列同时它也适用于需要专家知识、专业化视角Expert knowledge, specialized perspectives的任务。当你的目标是提升准确率时官方建议转向思维链、自验证等推理类技术而当目标是创意生成或专业视角输出时角色提示是第一顺位。零样本家族中的位置角色提示属于 Instructor 提示技术图谱中零样本Zero-Shot分支的一员。该分支中的所有技术都以不给示例、只改提示为前提包括技术作用典型场景角色提示Role Prompting为模型分配特定角色专家知识、专业化视角情感语言Emotional Language在提示中注入情感语气创意写作、共情回复风格定义Style Definition明确指定写作风格特定语气/格式的内容提示精炼Prompt Refinement自动优化提示词结果的迭代改进视角模拟Perspective Simulation让模型采纳不同视角多利益相关方分析与同为零样本技术的 风格提示Style Prompting 相比角色提示更侧重身份而风格提示更侧重输出约束写作风格、语气、情绪、体裁。二者可以叠加使用先用角色锁定身份再用风格约束输出形式从而把开放式任务一步步收窄到可控范围。用 Instructor 实现角色提示完整可运行示例原文档给出了一个将角色提示与结构化输出结合的最小实现核心模式是把角色声明拼进 system 消息同时用 Pydantic 模型约束返回结构。完整代码如下import openai import instructor from pydantic import BaseModel client instructor.from_provider(openai/gpt-5-nano) class Response(BaseModel): poem: str def role_prompting(query, role): return client.create( modelgpt-4o, response_modelResponse, messages[ { role: system, content: f{role} {query}, }, ], ) if __name__ __main__: query Write me a short poem about coffee. role You are a renowned poet. response role_prompting(query, role) print(response.poem) In the mornings gentle light, A brew of warmth, dark and bright. Awakening dreams, so sweet, In every sip, the day we greet. Through the steam, stories spin, A liquid muse, caffeine within. Moments pause, thoughts unfold, In coffees embrace, we find our gold. 这段代码的关键点在于client.create的调用方式instructor.from_provider(openai/gpt-5-nano)用一行代码创建统一接口的 Instructor 客户端详见下文源码分析response_modelResponse声明响应结构——模型输出会被强制解析为Response实例保证poem字段存在且为字符串messages中的role: system是角色注入点角色文本与查询文本拼接后整体交给系统消息返回的response.poem是已经过 Pydantic 验证的结构化字段而非原始 JSON 文本。运行这段代码即可得到一首结构完整的咖啡主题短诗——角色声明你是一位著名的诗人renowned poet直接决定了输出的文学性。深入源码from_provider 与 create 的调用链为了让上面的示例真正可运行有必要理解 Instructor 的两个底层入口。它们位于仓库的核心实现中是全部提示技术包括角色提示落地的公共底座。from_provider统一客户端工厂instructor.from_provider的实现位于 instructor/v2/auto_client.py。其签名要求模型字符串必须符合provider/model-name格式例如openai/gpt-4o、anthropic/claude-3-5-sonnet否则会抛出ConfigurationError。函数内部会根据 provider 前缀查找对应的构建器_PROVIDER_BUILDERS自动完成底层 SDK 客户端的创建与 Instructor 的接入对 OpenAI 系含 Azure、Databricks 及各类 OpenAI 兼容网关构建器会创建openai.OpenAI/AsyncOpenAI客户端并透传api_key、base_url、timeout、max_retries、organization、default_headers等参数对 Anthropic会自动补齐max_tokens默认 4096并注入 User-Agent对 Google支持vertexaiTrue、project、location等 Vertex AI 配置。同时from_provider支持async_clientTrue返回异步客户端、cacheAutoCache(...)启用响应缓存、mode覆盖默认模式OpenAI 默认Mode.TOOLS。切换提供商只需修改一个字符串业务代码完全不变。更完整的参数说明见 docs/concepts/from_provider.md。client.create结构化输出的核心方法create的默认实现位于 instructor/v2/core/client.py签名如下def create( self, messages: str | list[ChatCompletionMessageParam] | None None, response_model: type[T] | None None, max_retries: int | Retrying 3, context: dict[str, Any] | None None, strict: bool True, token_budget: int | None None, **kwargs, ) - T | Any:其中几个参数对角色提示实战至关重要messages消息列表角色提示就注入在system消息中也可以直接传一个字符串response_modelPydantic 模型决定输出的强制结构是角色生成内容之后保证可编程消费的关键max_retries默认 3 次当模型输出无法通过 Pydantic 校验时自动重试——角色提示如果导致输出格式偏离会在此机制下被纠正strict默认True开启严格 Schema 模式token_budget可选超出预算时触发截断/重试策略。调用链最终会把response_model、messages等参数透传给底层 SDK 的create由各提供商处理器完成函数调用tool call或 JSON 模式的组装与解析。角色提示 × 结构化输出Schema 层面的配合角色提示解决了说什么、以什么身份说而 Pydantic 模型解决了以什么结构返回。两者配合时可以遵循 docs/concepts/prompting.md 中的结构工程最佳实践把角色约束渗透进 Schema1. 用 docstring 与 Field 描述强化角色指令模型的类文档字符串docstring和字段描述会随 Schema 一起发给模型因此可以在其中重申角色要求形成双重约束from pydantic import BaseModel, Field class Poem(BaseModel): You are a renowned poet. Write in vivid, literary language. title: str Field(descriptionA striking, evocative title fitting the poem) poem: str Field(descriptionThe poem itself, written from the poets perspective)2. 角色 风格叠加把角色提示与 风格提示 组合可以同时锁定身份和输出约束写作风格、语气、情绪、体裁。例如将角色设为十九世纪浪漫主义诗人风格约束设为dramatic、flowery生成的诗歌会同时在身份与文体两个维度上符合预期。3. 角色字段化便于动态切换把角色从硬编码字符串提升为函数参数或配置字段如原文档role_prompting(query, role)的做法配合response_model的枚举字段可以实现按任务类型自动选角色的工厂模式from enum import Enum from pydantic import BaseModel, Field class Persona(Enum): POET You are a renowned poet. CRITIC You are a sharp literary critic. SCIENTIST You are a meticulous scientist. class PoemReview(BaseModel): verdict: str Field(descriptionThe critics final judgment) score: int Field(descriptionScore from 1 to 10)进阶多角色协作与角色选择的系统性方法原文档在More Role Prompting一节中提示了三条研究脉络这里将其转化为可落地的实践建议系统性地选择角色来自论文RoleLLM: Benchmarking, Eliciting, and Enhancing Role-Playing Abilities of Large Language Models。其思路是先构建角色库再根据任务特征评估并挑选最合适的角色。实操上可以为不同任务族准备一组候选角色通过小规模评测挑选表现最优者避免拍脑袋选角色。评估社交角色的影响来自论文Is A Helpful Assistant the Best Role for Large Language Models? A Systematic Evaluation of Social Roles in System Prompts。该研究系统评测了系统提示中的社交角色提示我们You are a helpful assistant未必是通用最优解角色与任务匹配才是关键。多角色自我协作来自论文Unleashing the Emergent Cognitive Synergy in Large Language Models: A Task-Solving Agent through Multi-Persona Self-Collaboration。即在同一任务中让多个角色如规划者执行者评审者依次登场各司其职后聚合结果。在 Instructor 中这可以通过多次create调用串联实现先以规划者角色生成方案再以执行者角色细化最后以评审者角色校验输出。常见问题与调试建议角色文本与查询拼接的歧义f{role} {query}的写法要求角色与查询都能被模型清楚解析建议角色以句号结尾、查询独立成句避免模型把两者混淆为同一指令。角色与响应结构冲突若角色暗示了极长的自由输出如写一部小说而response_model只定义了一个短字段模型可能在结构约束下大幅压缩内容。此时应调整字段描述或拆分输出模型。验证失败导致重试max_retries默认为 3。若角色提示诱使模型输出违反 Schema 的内容例如在poem: str里输出多段 MarkdownInstructor 会自动重试若持续失败可检查角色声明是否过于模糊。切换提供商角色提示通过标准system消息传递在 OpenAI、Anthropic、Google 等from_provider支持的提供商间切换时无需改动提示代码只需修改 provider 字符串各提供商对 system 消息的底层处理略有差异行为以官方文档为准。总结角色提示是最轻量的零样本性能提升手段一句角色声明即可重塑模型的输出立场与语言风格。在 Instructor 中它与from_provider统一客户端、create结构化输出和 Pydantic 响应模型天然衔接既能用于开放式创意生成也能叠加 Field 描述、风格约束和多角色协作形成系统化的提示工程方案。相关延伸阅读可回到本仓库的 提示技术总览以及 角色提示原始文档 中引用的 RoleLLM、社交角色评测与多角色自我协作三篇论文。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
