Prompt工程指南

Prompt工程指南

适用产品: RAILWISE-CLI | WorkWise | RAILWISE-TSM
目标读者: AI应用开发者、Prompt工程师、全栈工程师
阅读时间: 约25分钟

---

1. 概述

1.1 什么是Prompt工程

Prompt工程（Prompt Engineering）是指通过精心设计和优化输入提示（Prompt），引导大语言模型（LLM）生成准确、可靠、符合预期输出的技术实践。在RailWise的AI工程测绘系统中，Prompt工程是连接业务需求与AI能力的关键桥梁。

1.2 适用场景

场景	说明	典型产品
自动化监测报告生成	将监测数据转化为结构化报告	RAILWISE-TSM
测量数据智能解析	识别并提取测量原始数据中的关键信息	RAILWISE-CLI
工程异常诊断	基于监测数据自动分析异常原因	WorkWise
多智能体协作编排	协调多个AI Agent完成复杂任务	RAILWISE-CLI
代码辅助生成	生成TypeScript/Rust测量算法代码	全产品栈

1.3 技术原理

RailWise AI系统基于以下技术栈实现Prompt工程：

• 底层模型: 支持OpenAI GPT-4、Claude 3.5 Sonnet、本地LLM（Ollama/LM Studio）
• 编排框架: LangChain / LangGraph（多智能体工作流）
• Prompt管理: 版本化Prompt模板库，支持A/B测试
• 输出解析: 结构化输出（JSON Schema / Zod验证）

---

2. Prompt设计原则

2.1 清晰性原则（Clarity）

Prompt应当明确表达意图，避免歧义。

// ❌ 糟糕的Prompt
"分析这些数据"

// ✅ 优秀的Prompt
"你是一位轨道交通监测领域的资深工程师。请分析以下全站仪自动化监测数据，
识别是否存在异常变形趋势，并给出专业判断：

数据格式：每行包含[测点编号, X坐标(m), Y坐标(m), Z坐标(m), 观测时间]
判定标准：
- 单次变化量 > 2mm 为黄色预警
- 累计变化量 > 5mm 或变化速率 > 1mm/天 为红色预警

请输出JSON格式：{ status: 'normal'|'warning'|'alert', details: [...] }"

2.2 结构化原则（Structure）

使用明确的结构化格式组织Prompt内容。

## 角色定义
你是一位具有10年经验的轨道交通监测工程师...

## 任务描述
请对以下监测数据进行变形分析...

## 输入数据
[在此处插入数据]

## 约束条件
1. 只输出JSON格式
2. 不要包含任何解释性文字
3. 时间格式使用ISO 8601

## 输出格式
```json
{
  "analysis_id": "string",
  "status": "normal|warning|alert",
  "measurements": [...],
  "recommendations": [...]
}

### 2.3 上下文原则（Context）

提供充分的领域上下文，帮助模型理解专业场景。

```typescript
// 工程上下文示例
const engineeringContext = `
【项目背景】
- 工程名称：宁波轨道交通3号线控制保护区监测
- 监测对象：绕城高速管廊工程1标段施工影响区域
- 监测方法：自动化全站仪（Leica TM60）周期性观测
- 控制网等级：二等精度
- 允许变形值：水平位移≤10mm，沉降≤15mm

【数据说明】
- 坐标系统：宁波独立坐标系
- 高程基准：1985国家高程基准
- 观测周期：每4小时一次
- 测点布置：沿盾构隧道轴线每20m一个断面，每个断面5个测点
`;

2.4 示例驱动原则（Few-Shot）

通过示例引导模型理解期望的输出格式和质量标准。

const fewShotPrompt = `
## 示例1：正常状态
输入：
测点MP-01: X=29567.123, Y=10458.456, Z=12.345, 时间=2026-07-01T08:00:00Z
测点MP-01: X=29567.124, Y=10458.457, Z=12.346, 时间=2026-07-01T12:00:00Z

输出：
{"status":"normal","details":[{"point":"MP-01","dx":0.001,"dy":0.001,"dz":0.001,"trend":"stable"}]}

## 示例2：预警状态
输入：
测点MP-03: X=29589.123, Y=10472.456, Z=11.345, 时间=2026-07-01T08:00:00Z
测点MP-03: X=29589.145, Y=10472.478, Z=11.338, 时间=2026-07-01T12:00:00Z

输出：
{"status":"warning","details":[{"point":"MP-03","dx":0.022,"dy":0.022,"dz":-0.007,"trend":"accelerating","alert":"单次位移超阈值"}]}

## 现在请分析以下数据：
[实际输入数据]
`;

---

3. Prompt优化技巧

3.1 链式思考（Chain-of-Thought）

引导模型逐步推理，特别适用于复杂工程计算场景。

const cotPrompt = `
请按以下步骤分析监测数据：

步骤1：计算每个测点本次观测与初始值的坐标差
  ΔX = X_当前 - X_初始
  ΔY = Y_当前 - Y_初始
  ΔZ = Z_当前 - Z_初始

步骤2：计算水平位移量
  d_H = √(ΔX² + ΔY²)

步骤3：计算累计变化量
  d_累计 = √(ΔX_累计² + ΔY_累计² + ΔZ_累计²)

步骤4：判断预警等级
  - 若 d_H ≤ 2mm 且 |ΔZ| ≤ 2mm → 正常
  - 若 2mm < d_H ≤ 5mm 或 2mm < |ΔZ| ≤ 5mm → 黄色预警
  - 若 d_H > 5mm 或 |ΔZ| > 5mm → 红色预警

步骤5：输出分析结果

请展示完整的计算过程，然后给出最终结果。
`;

3.2 自我一致性（Self-Consistency）

对同一问题多次采样，取最一致的答案，提高可靠性。

import { OpenAI } from 'openai';

async function selfConsistencyAnalysis(
  prompt: string,
  samples: number = 5
): Promise<AnalysisResult> {
  const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

  const results: AnalysisResult[] = [];

  for (let i = 0; i < samples; i++) {
    const response = await client.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: prompt }],
      temperature: 0.7, // 适度随机性
    });

    const result = JSON.parse(response.choices[0].message.content!);
    results.push(result);
  }

  // 投票机制：取最频繁的status
  const statusCounts = results.reduce((acc, r) => {
    acc[r.status] = (acc[r.status] || 0) + 1;
    return acc;
  }, {} as Record<string, number>);

  const finalStatus = Object.entries(statusCounts)
    .sort((a, b) => b[1] - a[1])[0][0];

  return results.find(r => r.status === finalStatus)!;
}

3.3 输出格式强制（Output Format Enforcement）

使用JSON Schema或Zod强制约束输出格式。

import { z } from 'zod';

// 定义输出Schema
const MonitoringAnalysisSchema = z.object({
  analysis_id: z.string().uuid(),
  project_name: z.string(),
  observation_time: z.string().datetime(),
  status: z.enum(['normal', 'warning', 'alert', 'error']),
  measurements: z.array(z.object({
    point_id: z.string(),
    coordinate: z.object({
      x: z.number(),
      y: z.number(),
      z: z.number(),
    }),
    displacement: z.object({
      dx: z.number(),
      dy: z.number(),
      dz: z.number(),
      d_horizontal: z.number(),
      d_vertical: z.number(),
      d_total: z.number(),
    }),
    alert_level: z.enum(['none', 'yellow', 'red']),
    trend: z.enum(['stable', 'slow', 'accelerating', 'decelerating']),
  })),
  summary: z.object({
    total_points: z.number().int(),
    normal_count: z.number().int(),
    warning_count: z.number().int(),
    alert_count: z.number().int(),
  }),
  recommendations: z.array(z.string()).max(5),
});

type MonitoringAnalysis = z.infer<typeof MonitoringAnalysisSchema>;

// Prompt中嵌入Schema
const structuredPrompt = `
你必须严格按照以下JSON Schema输出分析结果：
${JSON.stringify(MonitoringAnalysisSchema.shape, null, 2)}

注意：
- 所有数值保留3位小数
- 时间使用ISO 8601格式
- 不要输出任何Schema以外的字段
`;

3.4 温度参数调优

根据任务类型选择合适的temperature值。

任务类型	推荐Temperature	说明
数据解析/结构化输出	0.0 - 0.2	确定性输出，减少幻觉
报告生成	0.3 - 0.5	平衡创造性与准确性
异常诊断	0.2 - 0.4	需要推理但保持客观
创意写作/营销文案	0.7 - 1.0	允许更多创造性
代码生成	0.1 - 0.3	语法正确性优先

---

4. 工程化Prompt管理

4.1 版本化Prompt模板

prompts/monitoring-analysis/v1.2.0.ts

export const MonitoringAnalysisPrompt = {
  version: '1.2.0',
  description: '全站仪监测数据分析Prompt模板',
  changelog: [
    '1.2.0: 增加趋势分析字段',
    '1.1.0: 支持多测点批量分析',
    '1.0.0: 初始版本',
  ],

  template: (params: {
    projectName: string;
    controlPoints: ControlPoint[];
    measurements: Measurement[];
    thresholds: AlertThresholds;
  }) => `
## 角色
你是一位轨道交通监测领域的高级工程师，具有15年全站仪自动化监测经验。

## 任务
对"${params.projectName}"的监测数据进行变形分析。

## 控制点信息
${params.controlPoints.map(cp => `- ${cp.id}: (${cp.x}, ${cp.y}, ${cp.z})`).join('\n')}

## 监测数据
${JSON.stringify(params.measurements, null, 2)}

## 预警阈值
- 单次位移预警：${thresholds.singleWarning}mm
- 单次位移报警：${thresholds.singleAlert}mm
- 累计位移报警：${thresholds.cumulativeAlert}mm

## 输出要求
[输出格式定义...]
`,
};

4.2 Prompt A/B测试框架

interface PromptExperiment {
  id: string;
  name: string;
  variants: PromptVariant[];
  metrics: string[]; // 评估指标
  sampleSize: number;
}

interface PromptVariant {
  id: string;
  prompt: string;
  model: string;
  temperature: number;
}

// 实验评估
async function evaluatePromptVariant(
  variant: PromptVariant,
  testCases: TestCase[]
): Promise<EvaluationResult> {
  const results = await Promise.all(
    testCases.map(async (tc) => {
      const output = await llm.generate(variant.prompt, tc.input);
      return {
        accuracy: calculateAccuracy(output, tc.expected),
        latency: output.latency,
        tokenUsage: output.usage.total_tokens,
        formatCompliance: validateSchema(output, tc.schema),
      };
    })
  );

  return aggregateResults(results);
}

4.3 Prompt缓存与复用

import { LRUCache } from 'lru-cache';

class PromptCache {
  private cache = new LRUCache<string, string>({
    max: 1000,
    ttl: 1000 * 60 * 60, // 1小时
  });

  getKey(prompt: string, params: Record<string, unknown>): string {
    return Bun.hash(`${prompt}:${JSON.stringify(params)}`).toString();
  }

  async getOrGenerate(
    prompt: string,
    params: Record<string, unknown>,
    generator: () => Promise<string>
  ): Promise<string> {
    const key = this.getKey(prompt, params);

    if (this.cache.has(key)) {
      return this.cache.get(key)!;
    }

    const result = await generator();
    this.cache.set(key, result);
    return result;
  }
}

---

5. 多智能体Prompt编排

5.1 Agent角色定义

// RAILWISE-CLI多智能体系统角色定义

export const SurveyAgent = {
  role: '测量工程师Agent',
  systemPrompt: `你是一位专业的工程测量Agent，负责：
1. 解析全站仪原始观测数据
2. 计算坐标、角度、距离
3. 进行平差计算
4. 输出标准化测量成果

约束：
- 所有计算遵循《工程测量标准》GB 50026
- 输出必须包含精度评定
- 发现超限数据必须标记`,
  tools: ['coordinate_calculation', 'adjustment_computation', 'data_parser'],
};

export const MonitorAgent = {
  role: '监测分析Agent',
  systemPrompt: `你是一位轨道交通监测分析Agent，负责：
1. 分析变形监测数据趋势
2. 识别异常变化
3. 生成预警报告
4. 提出处置建议

约束：
- 严格依据预警阈值进行分级
- 趋势分析需基于至少3期数据
- 报告需包含数据支撑`,
  tools: ['trend_analysis', 'alert_detection', 'report_generator'],
};

export const ReportAgent = {
  role: '报告生成Agent',
  systemPrompt: `你是一位监测报告编制Agent，负责：
1. 整合多源监测数据
2. 生成符合规范的技术报告
3. 制作图表和统计摘要
4. 输出Word/PDF格式

约束：
- 遵循《城市轨道交通监测技术规范》
- 报告结构：概述→数据→分析→结论→建议
- 图表需清晰标注单位和时间`,
  tools: ['docx_generator', 'chart_renderer', 'data_aggregator'],
};

5.2 多Agent协作流程

import { StateGraph, END } from '@langchain/langgraph';

// 定义工作流
const workflow = new StateGraph<AgentState>({
  channels: {
    rawData: { value: (x, y) => y ?? x, default: () => null },
    surveyResult: { value: (x, y) => y ?? x, default: () => null },
    analysisResult: { value: (x, y) => y ?? x, default: () => null },
    finalReport: { value: (x, y) => y ?? x, default: () => null },
  },
});

workflow
  .addNode('survey', async (state) => {
    const result = await SurveyAgent.process(state.rawData);
    return { surveyResult: result };
  })
  .addNode('analyze', async (state) => {
    const result = await MonitorAgent.process(state.surveyResult);
    return { analysisResult: result };
  })
  .addNode('report', async (state) => {
    const result = await ReportAgent.process({
      survey: state.surveyResult,
      analysis: state.analysisResult,
    });
    return { finalReport: result };
  })
  .addEdge('__start__', 'survey')
  .addEdge('survey', 'analyze')
  .addEdge('analyze', 'report')
  .addEdge('report', END);

const app = workflow.compile();
const result = await app.invoke({ rawData: measurementData });

---

6. 最佳实践

6.1 Prompt编写清单

• 明确定义AI角色和专业背景
• 提供充分的领域上下文
• 使用结构化格式（Markdown/JSON）
• 包含输入/输出示例（Few-Shot）
• 指定输出格式和约束条件
• 设置合理的温度参数
• 添加错误处理说明
• 版本化管理和变更记录

6.2 常见反模式

反模式	问题	改进方案
过度依赖模型推理	模型可能产生幻觉	提供明确的计算步骤和公式
模糊的任务描述	输出不一致	使用结构化模板和明确约束
忽略领域术语	模型理解偏差	在Prompt中定义专业术语
缺乏输出验证	格式错误	使用JSON Schema强制验证
硬编码敏感数据	安全风险	使用模板参数化

6.3 性能优化建议

1. Prompt压缩: 移除冗余文字，使用符号和缩写
2. 上下文精简: 只提供必要的上下文信息
3. 批量处理: 合并多个小请求为批量请求
4. 缓存策略: 对确定性Prompt结果进行缓存
5. 模型选择: 简单任务使用轻量模型，复杂任务使用强模型

---

7. 限制与注意事项

7.1 已知限制

• LLM不擅长精确数值计算，重要计算应使用专用算法
• 模型知识有截止日期，最新规范需显式提供
• 长文本处理存在上下文窗口限制（通常128K tokens）
• 多语言混合可能导致输出质量下降

7.2 安全注意事项

⚠️ 警告

• 切勿在Prompt中嵌入API密钥、密码等敏感信息
• 对模型输出进行验证，不要直接用于工程决策
• 涉及安全关键决策时，必须人工复核
• 遵守数据隐私法规，脱敏处理后再输入模型

---

8. 常见问题

Q: 如何处理超长监测数据？

A: 采用分块策略，将数据按时间或测点分组，分别处理后再聚合结果。或使用RAG（检索增强生成）技术，只提供相关片段。

Q: 模型输出不稳定怎么办？

A: 降低temperature至0.1-0.2，使用Few-Shot示例，启用Self-Consistency投票机制，或切换至确定性更高的模型。

Q: 如何提高数值计算准确性？

A: 在Prompt中提供明确的计算公式和步骤，要求模型展示计算过程，最终使用程序验证关键数值。

Q: 支持哪些模型？

A: RailWise CLI支持OpenAI GPT-4/4o、Claude 3.5 Sonnet、Gemini Pro、本地模型（通过Ollama）。详见AI模型配置指南。

---

9. 相关文档

• Prompt模板库 — 预置Prompt模板集合
• AI智能体Prompt模式 — 多智能体Prompt设计模式
• RAILWISE-CLI开发指南 — CLI工具开发文档
• AI模型配置指南 — 模型接入与配置
• MCP Server概述 — MCP工具集成

---

10. 更新日志

版本	日期	变更内容
1.0.0	2026-07-08	初始版本，包含Prompt设计原则、优化技巧、工程化方法

---

本文档由RailWise技术团队维护，如有疑问请联系技术支持：support@railwise.cn