大模型应用开发：Prompt Engineering 从经验法则到工程化实践

大模型应用开发：Prompt Engineering 从经验法则到工程化实践

一、Prompt 的"玄学"困境：调参靠运气，上线靠祈祷

大模型应用开发中，Prompt 设计是最容易被低估的环节。很多团队把 Prompt 当作"提示词"随手写，上线后发现模型输出不稳定------同样的 Prompt，今天输出格式正确，明天就多了一行解释；要求输出 JSON，偶尔夹带一段自然语言；要求只回答 A 或 B，有时回答"我认为应该选 A"。这不是模型的问题，而是 Prompt 缺乏工程化设计。

Prompt Engineering 的核心目标不是"让模型回答正确"，而是"让模型稳定地以预期格式输出"。这需要从经验驱动的"调参"升级为工程化的"设计-测试-迭代"流程。具体包括：结构化 Prompt 模板、输出格式约束、Few-Shot 示例选择策略、以及自动化的 Prompt 回归测试。

二、工程化 Prompt 设计的架构

flowchart TD A[用户输入] --> B[Prompt 模板引擎] B --> C[结构化 Prompt 组装] C --> D[系统指令: 角色与约束] C --> E[上下文: 检索结果 / 历史对话] C --> F[Few-Shot 示例: 格式示范] C --> G[用户输入: 实际问题] C --> H[输出格式: JSON Schema 约束] D --> I[完整 Prompt] E --> I F --> I G --> I H --> I I --> J[大模型推理] J --> K[输出解析器] K --> L{格式校验} L -->|通过| M[返回结构化结果] L -->|失败| N[重试 / 降级策略] style B fill:#bbf,stroke:#333 style K fill:#f9f,stroke:#333 style L fill:#fbb,stroke:#333

关键设计原则：

• 角色与约束分离：系统指令定义模型角色和行为边界，与具体问题解耦
• Few-Shot 策略化：示例不是随机挑选，而是覆盖边界情况（如空值、多义、冲突）
• 输出格式强制：通过 JSON Schema 约束输出结构，解析器做格式校验和重试
• Prompt 版本化：每次修改 Prompt 都记录版本和效果，支持 A/B 测试和回滚

三、生产级代码实现

3.1 结构化 Prompt 模板引擎

# prompt_template.py
# 结构化 Prompt 模板引擎
from dataclasses import dataclass, field
from typing import Optional
import json


@dataclass
class PromptTemplate:
    """结构化 Prompt 模板"""
    name: str
    version: str
    system_instruction: str
    output_schema: dict
    few_shot_examples: list[dict] = field(default_factory=list)
    max_retries: int = 2
    temperature: float = 0.1

    def build(
        self,
        user_input: str,
        context: Optional[str] = None,
    ) -> list[dict]:
        """组装完整的 Prompt 消息列表"""
        messages = []

        # 1. 系统指令：角色 + 约束 + 输出格式
        system_content = self.system_instruction
        system_content += "\n\n## 输出格式要求\n"
        system_content += (
            "你必须严格按照以下 JSON Schema 输出，"
            "不要输出任何 JSON 之外的内容：\n"
        )
        system_content += f"```json\n{json.dumps(self.output_schema, ensure_ascii=False, indent=2)}\n```"

        messages.append({
            "role": "system",
            "content": system_content
        })

        # 2. Few-Shot 示例
        for example in self.few_shot_examples:
            messages.append({
                "role": "user",
                "content": example["input"]
            })
            messages.append({
                "role": "assistant",
                "content": json.dumps(
                    example["output"],
                    ensure_ascii=False
                )
            })

        # 3. 上下文（如 RAG 检索结果）
        if context:
            messages.append({
                "role": "user",
                "content": f"参考信息：\n{context}"
            })

        # 4. 用户输入
        messages.append({
            "role": "user",
            "content": user_input
        })

        return messages


# 预定义模板：意图识别
INTENT_CLASSIFICATION = PromptTemplate(
    name="intent_classification",
    version="2.1",
    system_instruction=(
        "你是一个意图识别系统。根据用户输入，判断其意图类别。\n"
        "只输出 JSON，不要输出任何解释或额外文本。\n"
        "如果无法判断意图，将 confidence 设为 0.0。"
    ),
    output_schema={
        "type": "object",
        "properties": {
            "intent": {
                "type": "string",
                "enum": ["query", "complaint", "refund", "chitchat", "other"]
            },
            "confidence": {
                "type": "number",
                "minimum": 0.0,
                "maximum": 1.0
            },
            "sub_intent": {
                "type": "string"
            }
        },
        "required": ["intent", "confidence"]
    },
    few_shot_examples=[
        {
            "input": "我的订单怎么还没到",
            "output": {
                "intent": "complaint",
                "confidence": 0.92,
                "sub_intent": "delivery_delay"
            }
        },
        {
            "input": "你好呀",
            "output": {
                "intent": "chitchat",
                "confidence": 0.95,
                "sub_intent": "greeting"
            }
        },
        # 边界示例：模糊输入
        {
            "input": "这个不太行",
            "output": {
                "intent": "other",
                "confidence": 0.3,
                "sub_intent": "ambiguous"
            }
        }
    ],
    temperature=0.1
)

3.2 输出解析与格式校验

# output_parser.py
# 模型输出解析与格式校验
import json
import re
import logging
from typing import Optional, TypeVar, Type
from dataclasses import dataclass

logger = logging.getLogger("prompt-parser")

T = TypeVar("T")


@dataclass
class ParseResult:
    """解析结果"""
    success: bool
    data: Optional[dict] = None
    raw_output: str = ""
    error: str = ""
    retry_count: int = 0


class OutputParser:
    """模型输出解析器"""

    def __init__(self, schema: dict):
        self.schema = schema

    def parse(self, raw_output: str) -> ParseResult:
        """解析模型输出为结构化数据"""
        # Step 1: 提取 JSON 内容
        json_str = self._extract_json(raw_output)
        if json_str is None:
            return ParseResult(
                success=False,
                raw_output=raw_output,
                error="无法从输出中提取 JSON"
            )

        # Step 2: 解析 JSON
        try:
            data = json.loads(json_str)
        except json.JSONDecodeError as e:
            return ParseResult(
                success=False,
                raw_output=raw_output,
                error=f"JSON 解析失败: {e}"
            )

        # Step 3: Schema 校验
        validation_error = self._validate_schema(data)
        if validation_error:
            return ParseResult(
                success=False,
                raw_output=raw_output,
                error=validation_error
            )

        return ParseResult(
            success=True,
            data=data,
            raw_output=raw_output
        )

    def _extract_json(self, text: str) -> Optional[str]:
        """从模型输出中提取 JSON 字符串"""
        # 策略 1: 直接解析（理想情况）
        text = text.strip()
        if text.startswith("{") and text.endswith("}"):
            return text

        # 策略 2: 从 Markdown 代码块中提取
        pattern = r"```(?:json)?\s*\n?(.*?)\n?```"
        match = re.search(pattern, text, re.DOTALL)
        if match:
            return match.group(1).strip()

        # 策略 3: 找到第一个 { 和最后一个 }
        start = text.find("{")
        end = text.rfind("}")
        if start != -1 and end > start:
            return text[start:end + 1]

        return None

    def _validate_schema(self, data: dict) -> Optional[str]:
        """简化版 Schema 校验"""
        required = self.schema.get("required", [])
        properties = self.schema.get("properties", {})

        # 检查必填字段
        for field_name in required:
            if field_name not in data:
                return f"缺少必填字段: {field_name}"

        # 检查枚举值
        for field_name, field_schema in properties.items():
            if field_name not in data:
                continue
            if "enum" in field_schema:
                if data[field_name] not in field_schema["enum"]:
                    return (
                        f"字段 {field_name} 的值 "
                        f"'{data[field_name]}' 不在枚举范围内: "
                        f"{field_schema['enum']}"
                    )
            # 检查数值范围
            if "minimum" in field_schema:
                if isinstance(data[field_name], (int, float)):
                    if data[field_name] < field_schema["minimum"]:
                        return (
                            f"字段 {field_name} 的值 "
                            f"{data[field_name]} 小于最小值 "
                            f"{field_schema['minimum']}"
                        )

        return None

3.3 自动化 Prompt 回归测试

# prompt_regression_test.py
# Prompt 变更的自动化回归测试
import json
import time
from dataclasses import dataclass
from typing import Callable


@dataclass
class TestCase:
    """测试用例"""
    name: str
    user_input: str
    context: str = ""
    expected_intent: str = ""
    expected_confidence_min: float = 0.0
    custom_assertion: Callable[[dict], bool] = None


@dataclass
class TestResult:
    """测试结果"""
    name: str
    passed: bool
    actual_output: dict = None
    error: str = ""
    latency_ms: float = 0


class PromptRegressionTester:
    """Prompt 回归测试器"""

    def __init__(
        self,
        template: "PromptTemplate",
        llm_client,  # 大模型客户端
        parser: "OutputParser"
    ):
        self.template = template
        self.llm_client = llm_client
        self.parser = parser

    def run_test(self, test_case: TestCase) -> TestResult:
        """执行单个测试用例"""
        messages = self.template.build(
            user_input=test_case.user_input,
            context=test_case.context or None
        )

        start = time.perf_counter()
        raw_output = self.llm_client.chat(
            messages=messages,
            temperature=self.template.temperature
        )
        latency = (time.perf_counter() - start) * 1000

        parse_result = self.parser.parse(raw_output)

        if not parse_result.success:
            return TestResult(
                name=test_case.name,
                passed=False,
                error=f"解析失败: {parse_result.error}",
                latency_ms=latency
            )

        # 断言检查
        data = parse_result.data

        # 检查意图
        if test_case.expected_intent:
            if data.get("intent") != test_case.expected_intent:
                return TestResult(
                    name=test_case.name,
                    passed=False,
                    actual_output=data,
                    error=(
                        f"意图不匹配: 期望 '{test_case.expected_intent}', "
                        f"实际 '{data.get('intent')}'"
                    ),
                    latency_ms=latency
                )

        # 检查置信度下限
        if test_case.expected_confidence_min > 0:
            conf = data.get("confidence", 0)
            if conf < test_case.expected_confidence_min:
                return TestResult(
                    name=test_case.name,
                    passed=False,
                    actual_output=data,
                    error=(
                        f"置信度过低: 期望 >= {test_case.expected_confidence_min}, "
                        f"实际 {conf}"
                    ),
                    latency_ms=latency
                )

        # 自定义断言
        if test_case.custom_assertion and not test_case.custom_assertion(data):
            return TestResult(
                name=test_case.name,
                passed=False,
                actual_output=data,
                error="自定义断言失败",
                latency_ms=latency
            )

        return TestResult(
            name=test_case.name,
            passed=True,
            actual_output=data,
            latency_ms=latency
        )

    def run_suite(
        self, test_cases: list[TestCase]
    ) -> dict:
        """执行完整测试套件"""
        results = []
        for tc in test_cases:
            result = self.run_test(tc)
            results.append(result)
            status = "PASS" if result.passed else "FAIL"
            print(f"  [{status}] {result.name}: {result.error or 'OK'}")

        passed = sum(1 for r in results if r.passed)
        total = len(results)
        avg_latency = sum(r.latency_ms for r in results) / total

        return {
            "total": total,
            "passed": passed,
            "failed": total - passed,
            "pass_rate": f"{passed/total:.1%}",
            "avg_latency_ms": round(avg_latency, 1)
        }

3.4 带重试的推理封装

# robust_inference.py
# 带重试和降级的推理封装
import logging
from prompt_template import PromptTemplate
from output_parser import OutputParser, ParseResult

logger = logging.getLogger("robust-inference")


class RobustInference:
    """带重试和降级的推理封装"""

    def __init__(
        self,
        template: PromptTemplate,
        llm_client,
        parser: OutputParser,
        fallback_value: dict = None
    ):
        self.template = template
        self.llm_client = llm_client
        self.parser = parser
        self.fallback_value = fallback_value or {}

    def invoke(
        self,
        user_input: str,
        context: str = None
    ) -> ParseResult:
        """执行推理，带自动重试"""
        messages = self.template.build(
            user_input=user_input,
            context=context
        )

        for attempt in range(self.template.max_retries + 1):
            raw_output = self.llm_client.chat(
                messages=messages,
                temperature=self.template.temperature
            )
            result = self.parser.parse(raw_output)

            if result.success:
                result.retry_count = attempt
                return result

            logger.warning(
                f"解析失败 (尝试 {attempt + 1}/"
                f"{self.template.max_retries + 1}): "
                f"{result.error}"
            )

            # 重试时在用户消息末尾追加格式提醒
            if attempt < self.template.max_retries:
                messages.append({
                    "role": "assistant",
                    "content": raw_output
                })
                messages.append({
                    "role": "user",
                    "content": (
                        "你的输出格式不正确，请严格按照 "
                        "JSON Schema 重新输出，"
                        "只输出 JSON，不要输出其他内容。"
                    )
                })

        # 所有重试失败，返回降级结果
        logger.error(
            f"所有重试失败，返回降级值: {self.fallback_value}"
        )
        return ParseResult(
            success=False,
            data=self.fallback_value,
            raw_output=raw_output,
            error=f"重试 {self.template.max_retries} 次后仍失败",
            retry_count=self.template.max_retries
        )

四、Prompt 工程化的隐性代价：Token 开销、测试维护与模型绑定

Prompt 工程化不是免费的，以下 Trade-offs 需要在架构决策中权衡：

Token 开销。结构化 Prompt（系统指令 + JSON Schema + Few-Shot 示例）的 Token 消耗远高于简单提示词。一个完整的意图识别 Prompt 可能消耗 500-800 个 Token，而简单提示词只需 50 个。在百万级日请求量下，Token 成本差异显著。优化手段：精简 JSON Schema 描述（只保留必要约束）、动态选择 Few-Shot 示例（只选与当前输入最相关的 2-3 个）。

测试维护成本。Prompt 回归测试套件需要持续维护------业务规则变更时，测试用例要同步更新；模型版本升级时，预期输出可能变化。如果测试用例过于严格（如精确匹配整个 JSON），模型输出的微小变化就会导致测试失败。建议测试用例只校验关键字段（如 intent 和 confidence），而非全量匹配。

模型绑定风险。针对特定模型优化的 Prompt，换到另一个模型可能效果完全不同。GPT-4 的指令遵循能力强，Claude 偏好 XML 格式，开源模型对复杂指令的理解能力有限。如果应用需要支持多模型，Prompt 模板需要做模型适配层。建议将模型相关的格式偏好（如 JSON vs XML）抽离为可配置项。

重试的延迟代价。带重试的推理封装，最坏情况下延迟是单次推理的 N+1 倍。对于实时交互场景（如客服对话），3 次重试可能导致 3-6 秒的响应延迟。建议设置总超时（如 2 秒），超时后直接返回降级结果，而非无限重试。

五、总结

Prompt Engineering 的工程化实践，核心价值在于将"经验驱动的调参"升级为"设计-测试-迭代的工程流程"，让大模型应用的输出稳定可预期。落地要点如下：

1. 结构化模板：系统指令、Few-Shot 示例、输出格式约束分离组装，而非一整段文本
2. 格式强制：通过 JSON Schema 约束输出结构，解析器做格式校验，不合法则重试
3. 边界覆盖：Few-Shot 示例必须包含边界情况（空值、模糊输入、冲突信息），而非只选"正常"案例
4. 回归测试：每次修改 Prompt 前跑回归测试套件，量化变更对输出质量的影响
5. 降级兜底：重试失败后返回预定义的降级值，避免应用崩溃