Prompt Engineering从原理到实战

# ❌ 模糊的 prompt
prompt = "帮我分析这段代码的问题"

# ✅ 清晰的 prompt
prompt = """你是一位拥有10年经验的 Python 后端工程师，专精代码审查。
请从以下维度分析这段代码的问题：
1. 逻辑正确性
2. 性能瓶颈
3. 安全隐患
4. 代码风格与可维护性"""

# ❌ 模糊的格式要求
prompt = "列出学习 Python 的资源"

# ✅ 精确指定格式
prompt = """请推荐 5 个学习 Python 的在线资源。
对每个资源，请按以下 JSON 格式输出：
{
  "name": "资源名称",
  "url": "链接",
  "level": "beginner | intermediate | advanced",
  "focus": "主要学习方向",
  "reason": "推荐理由（一句话）"
}
请以 JSON 数组形式返回所有结果。"""

prompt = """请为一款面向日本市场的健康饮品写一段广告文案。

约束条件：
- 字数：100-150个日文字符
- 语调：温暖、亲切，面向30-40岁女性
- 必须包含：产品名"朝のめぐみ"
- 不得包含：与竞品的直接比较、夸大的健康声明
- 格式：一个主标题 + 一段正文"""

prompt = """请将以下用三重反引号包裹的用户评论分类为"正面"、"负面"或"中性"。

用户评论：
\```
这家餐厅的拉面味道还不错，但是等了40分钟实在太久了。下次可能会考虑其他店。
\```

请只输出分类结果，不需要解释。"""

prompt = """请按以下步骤分析这篇新闻文章：

步骤 1：用一句话总结文章的核心事件
步骤 2：识别文章中提到的所有人物及其角色
步骤 3：判断文章的情感倾向（正面/负面/中性），并给出依据
步骤 4：基于以上分析，生成 3 个关键标签

文章内容：
---
{article_text}
---

请按步骤编号依次输出结果。"""

# ❌ 只说不做什么
prompt = "回答用户的问题，不要编造信息，不要太长，不要太短"

# ✅ 明确说做什么
prompt = """回答用户的问题。
- 只基于提供的文档内容回答
- 如果文档中没有相关信息，回复"根据现有资料无法回答此问题"
- 回答长度控制在 2-3 个段落
- 在回答末尾引用具体的文档段落作为出处"""

def build_analysis_prompt(user_text: str, language: str = "zh") -> str:
    """
    构建一个结构化的文本分析 prompt。
    注意：这就是 AI Application Engineer 的日常工作之一 ——
    将 prompt engineering 原则封装成可复用的函数。
    """
    system_prompt = f"""你是一位专业的文本分析助手。
你的任务是对用户提供的文本进行结构化分析。
输出语言：{"中文" if language == "zh" else "English"}"""

    user_prompt = f"""请分析以下文本，按指定的 JSON 格式输出结果。

待分析文本：
---
{user_text}
---

输出格式：
{{
  "summary": "一句话摘要",
  "sentiment": "positive | negative | neutral",
  "confidence": 0.0-1.0,
  "key_entities": ["实体1", "实体2"],
  "topics": ["话题1", "话题2"]
}}

要求：
1. summary 不超过 50 个字
2. confidence 为你对 sentiment 判断的置信度
3. key_entities 最多提取 5 个
4. 只输出 JSON，不要添加任何其他文字"""

    return system_prompt, user_prompt

# Zero-shot（零样本）
zero_shot_prompt = """判断以下评论的情感倾向。

评论：这家店的服务态度真的很差，等了一个小时才上菜。
情感："""
# 模型可能输出"负面"，也可能输出"消极"、"不好"、"negative" —— 格式不可控

# Few-shot（少样本）
few_shot_prompt = """判断评论的情感倾向。

评论：今天天气真好，心情特别愉快！
情感：positive

评论：这个产品质量一般般，没什么特别的。
情感：neutral

评论：快递太慢了，包装还破了，非常失望。
情感：negative

评论：这家店的服务态度真的很差，等了一个小时才上菜。
情感："""
# 模型现在非常明确地知道：输出只能是 positive / neutral / negative

# ❌ 差的 few-shot：示例太相似
bad_examples = """
输入：苹果 → 类别：水果
输入：香蕉 → 类别：水果
输入：橙子 → 类别：水果
"""

# ✅ 好的 few-shot：覆盖不同类别和边界情况
good_examples = """
输入：苹果 → 类别：水果
输入：胡萝卜 → 类别：蔬菜
输入：三文鱼 → 类别：海鲜
输入：番茄 → 类别：蔬菜（注：虽然有时被归为水果，但在烹饪分类中属于蔬菜）
"""

import numpy as np
from typing import List, Tuple

class DynamicFewShotSelector:
    """
    动态 few-shot 示例选择器。
    核心思路：根据用户输入，从示例库中选择最相关的示例。
    这是 AI 应用开发中的高频模式 —— 不要硬编码示例，要动态检索。
    """

    def __init__(self, examples: List[Tuple[str, str]], embedding_func):
        """
        参数:
            examples: [(input_text, output_text), ...] 示例库
            embedding_func: 将文本转为向量的函数
        """
        self.examples = examples
        self.embedding_func = embedding_func
        # 预计算所有示例的 embedding
        self.example_embeddings = [
            embedding_func(inp) for inp, _ in examples
        ]

    def select(self, query: str, k: int = 3) -> List[Tuple[str, str]]:
        """
        选出与 query 最相似的 k 个示例。
        使用余弦相似度作为相似性度量。
        """
        query_embedding = self.embedding_func(query)

        # 计算 query 与每个示例的余弦相似度
        similarities = []
        for emb in self.example_embeddings:
            cos_sim = np.dot(query_embedding, emb) / (
                np.linalg.norm(query_embedding) * np.linalg.norm(emb)
            )
            similarities.append(cos_sim)

        # 取 top-k 最相似的示例
        top_k_indices = np.argsort(similarities)[-k:]

        # 返回示例，注意：最相似的放在最后（利用 recency bias）
        return [self.examples[i] for i in top_k_indices]

    def build_prompt(self, query: str, k: int = 3) -> str:
        """组装完整的 few-shot prompt"""
        selected = self.select(query, k)

        prompt_parts = []
        for inp, out in selected:
            prompt_parts.append(f"输入：{inp}\n输出：{out}")

        prompt_parts.append(f"输入：{query}\n输出：")

        return "\n\n".join(prompt_parts)

# ❌ 不使用 CoT（直接要答案）
prompt_no_cot = """
餐厅账单是 180 元，需要加 10% 的服务费，三个人平分。
每人需要付多少钱？
"""
# 模型可能直接给出答案，但复杂数学问题时容易出错

# ✅ 使用 CoT（要求展示推理过程）
prompt_with_cot = """
餐厅账单是 180 元，需要加 10% 的服务费，三个人平分。
每人需要付多少钱？

请一步一步地思考这个问题，展示你的推理过程，最后给出答案。
"""
# 模型输出：
# 1. 原始账单：180 元
# 2. 服务费：180 × 10% = 18 元
# 3. 总计：180 + 18 = 198 元
# 4. 每人：198 ÷ 3 = 66 元
# 答案：每人需要付 66 元

prompt = f"""
{your_question}

Let's think step by step.
"""

prompt = """请解决以下数学问题。

问题：小明有 5 个苹果，他给了小红 2 个，然后妈妈又给了他 3 个。小明现在有几个苹果？
推理过程：
- 初始：小明有 5 个苹果
- 给了小红 2 个后：5 - 2 = 3 个
- 妈妈给了 3 个后：3 + 3 = 6 个
答案：6 个

问题：一个图书馆有 3 层，每层有 4 个书架，每个书架有 5 层隔板，每层隔板放 8 本书。图书馆一共有多少本书？
推理过程：
- 每个书架的书：5 层 × 8 本 = 40 本
- 每层楼的书：4 个书架 × 40 本 = 160 本
- 整个图书馆：3 层 × 160 本 = 480 本
答案：480 本

问题：{new_question}
推理过程："""

prompt = """你是一个医疗分诊助手。根据患者描述，进行初步分诊评估。

请严格按以下结构输出你的分析：

<reasoning>
<symptom_extraction>
[从描述中提取关键症状，列出每个症状]
</symptom_extraction>

<severity_assessment>
[评估每个症状的严重程度：轻微/中等/严重]
</severity_assessment>

<possible_conditions>
[基于症状组合，列出可能的病症，按可能性从高到低排列]
</possible_conditions>

<urgency_decision>
[综合判断：常规就诊/尽快就诊/紧急就医]
</urgency_decision>
</reasoning>

<final_answer>
[分诊建议（简洁版）]
</final_answer>

患者描述：{patient_description}"""

import json
import re
from dataclasses import dataclass
from typing import Optional


@dataclass
class ReasoningResult:
    """封装 CoT 输出的数据结构"""
    reasoning_steps: list[str]   # 推理步骤
    final_answer: str            # 最终答案
    confidence: float            # 置信度
    raw_output: str              # 模型原始输出


class ChainOfThoughtAnalyzer:
    """
    一个带有 Chain-of-Thought 推理能力的分析器。
    演示了如何在 AI 应用中工程化地使用 CoT。
    """

    def __init__(self, llm_client, model: str = "claude-sonnet-4-20250514"):
        self.client = llm_client
        self.model = model

    def analyze(self, question: str) -> ReasoningResult:
        """
        对问题进行 CoT 分析。
        关键设计：将推理过程和最终答案分离，方便下游处理。
        """
        prompt = self._build_cot_prompt(question)

        response = self.client.messages.create(
            model=self.model,
            max_tokens=2000,
            messages=[
                {"role": "system", "content": self._system_prompt()},
                {"role": "user", "content": prompt}
            ]
        )

        raw_output = response.content[0].text
        return self._parse_response(raw_output)

    def _system_prompt(self) -> str:
        return """你是一个严谨的分析助手。
在回答任何问题之前，你必须先展示完整的推理过程。
你的输出必须严格遵循指定的格式。"""

    def _build_cot_prompt(self, question: str) -> str:
        return f"""请分析以下问题。

问题：{question}

请按以下格式输出：

<reasoning>
步骤1: [第一步分析]
步骤2: [第二步分析]
...（根据需要添加更多步骤）
</reasoning>

<confidence>
[0.0 到 1.0 之间的数字，表示你对答案的置信度]
</confidence>

<answer>
[最终答案]
</answer>"""

    def _parse_response(self, raw: str) -> ReasoningResult:
        """
        解析模型的结构化输出。
        这就是为什么我们需要固定格式 —— 为了可靠地解析。
        """
        # 提取推理步骤
        reasoning_match = re.search(
            r'<reasoning>(.*?)</reasoning>', raw, re.DOTALL
        )
        reasoning_text = reasoning_match.group(1).strip() if reasoning_match else ""

        steps = [
            line.strip() for line in reasoning_text.split('\n')
            if line.strip() and line.strip().startswith('步骤')
        ]

        # 提取置信度
        conf_match = re.search(
            r'<confidence>(.*?)</confidence>', raw, re.DOTALL
        )
        try:
            confidence = float(conf_match.group(1).strip()) if conf_match else 0.5
        except ValueError:
            confidence = 0.5

        # 提取最终答案
        answer_match = re.search(
            r'<answer>(.*?)</answer>', raw, re.DOTALL
        )
        final_answer = answer_match.group(1).strip() if answer_match else raw

        return ReasoningResult(
            reasoning_steps=steps,
            final_answer=final_answer,
            confidence=confidence,
            raw_output=raw
        )

def build_email_reply_prompt(
    customer_email: str,
    customer_history: str,
    product_info: str
) -> tuple[str, str]:
    """
    综合运用 Clear Instructions + Few-Shot + CoT 的实战示例。
    场景：电商客服自动回复系统。
    """

    system_prompt = """你是"TechShop"的高级客服代表。
你的目标是：准确理解客户问题，提供有帮助的回复，维护品牌形象。

核心规则：
1. 始终保持礼貌和专业
2. 如果涉及退款，需要先验证订单信息
3. 如果问题超出你的处理范围，引导客户联系人工客服
4. 回复长度控制在 100-200 字"""  # ← Clear Instructions

    user_prompt = f"""请根据客户邮件生成回复。

=== 客户历史 ===
{customer_history}

=== 产品信息 ===
{product_info}

=== 参考示例 ===

【示例1】
客户邮件：我上周买的蓝牙耳机左耳没声音了，能换一个吗？
思考过程：
- 问题类型：产品质量问题
- 购买时间：一周内，在保修期
- 处理方式：应该提供换货服务
- 需要信息：订单号，以便查询
回复：您好！很抱歉听到您的耳机出现了问题。一周内的产品质量问题我们可以为您免费更换。麻烦您提供一下订单号，我会尽快为您安排换货流程。如有其他问题，随时联系我们！

【示例2】
客户邮件：你们能不能把我的订单地址改成大阪市？我下周要出差。
思考过程：
- 问题类型：订单修改（地址变更）
- 关键因素：需要确认订单是否已发货
- 处理方式：如果未发货可以修改，已发货需要拦截或转寄
- 需要信息：订单号，以便查询发货状态
回复：您好！地址变更没问题，不过需要先确认您的订单发货状态。请提供您的订单号，如果还未发货我们可以直接修改地址；如果已发货，我会帮您联系物流进行转寄。

=== 当前客户邮件 ===
{customer_email}

请先进行思考分析，然后生成回复。按以下格式输出：

思考过程：
[你的分析]

回复：
[给客户的回复]"""  # ← Few-Shot + CoT 组合

    return system_prompt, user_prompt