构建系统提示词探索器：工程化优化大语言模型应用性能

1. 项目概述：一个系统提示词探索器的诞生

最近在折腾大语言模型应用开发的朋友，估计都绕不开一个核心问题：如何设计一个真正好用、能稳定发挥模型潜能的系统提示词（System Prompt）？这玩意儿就像是给AI大脑安装的“底层操作系统”，直接决定了模型的行为模式、思考框架和输出质量。我见过太多项目，模型选型没问题，数据也喂得够，但最终效果就是差强人意，一排查，十有八九是系统提示词这块没打磨到位。

我自己在开发一个内部代号为“sys-fairy-eve”的探索工具时，也深陷其中。从最初拍脑袋写几句规则，到后来被各种边界情况、逻辑冲突搞得焦头烂额，我意识到，系统提示词的设计远不是“写一段话”那么简单，它是一个需要系统化探索、测试和迭代的工程问题。于是，就有了这个“nightly-mvp-2026-04-03-system-prompt-explorer”项目。本质上，它是一个用于系统化探索、评估和优化大语言模型系统提示词的轻量级框架或工具集。叫它“探索器”（Explorer）很贴切，因为它不是最终的生产部署方案，而是一个帮助我们在“提示词空间”里高效寻路、测绘和试错的工具。

这个MVP（最小可行产品）版本的目标很明确：为开发者，特别是那些深度依赖大语言模型API构建应用的朋友，提供一个结构化的方法来管理提示词实验。它要解决的痛点包括：提示词版本混乱、A/B测试成本高、效果评估主观、迭代过程不可追溯。通过这个工具，我希望能把提示词工程从“玄学”和“手工劳动”中解放出来，引入一些工程化的思想和可量化的手段。

2. 核心设计思路与架构拆解

2.1 为什么需要专门的提示词探索器？

在深入代码之前，我们先聊聊为什么普通的文本编辑器加API调用不能满足需求。假设你要优化一个客服机器人的系统提示词，你可能会经历：写一个版本V1，调用API测试几个问题，感觉不错；改出V2，再测试，好像回复变啰嗦了；改回V1的某个部分形成V3……很快，你就记不清哪个版本对应哪个文件，哪个回复是哪个版本产生的，更别提系统性地对比不同版本在数十个测试用例上的表现差异了。

“system-prompt-explorer”的设计核心，就是引入软件工程中的一些基本理念到提示词开发流程中：

1. 版本控制：像管理代码一样管理提示词，每一次修改都有记录，可回溯。
2. 实验管理：将一次完整的测试（包含系统提示词、用户输入、模型参数、输出结果）定义为一个“实验”，并集中管理。
3. 批量评估：提供自动化或半自动化的方式，用一组预设的、覆盖边界的测试用例集（Test Suite）来评估提示词效果。
4. 量化对比：不仅仅是看输出“感觉”如何，而是尝试引入可量化的评估指标（如相关性、安全性评分、长度控制、特定关键词出现频率等），尽管完全自动化评估LLM输出仍是挑战，但我们可以设计代理指标。

2.2 项目架构的核心组件

基于上述思路，我设计的探索器MVP包含了以下几个核心模块，它们共同构成了一个闭环的工作流：

1. 提示词仓库（Prompt Registry）：这不是一个复杂的数据库，在MVP阶段，我选择用结构化的YAML或JSON文件来存储不同版本的系统提示词。每个条目包含：唯一ID、提示词内容、创建时间、作者、以及关键的“元数据”标签（例如：风格: 简洁专业，目标: 信息提取，约束: 禁止虚构）。这解决了版本混乱的问题。

2. 实验运行器（Experiment Runner）：这是工具的执行引擎。它的职责是：

   • 加载指定的系统提示词版本。
   • 读取预设的测试用例集（一个包含各种用户查询的列表）。
   • 配置模型参数（如使用的API、模型名称、temperature、max_tokens等）。
   • 循环调用大语言模型API（如OpenAI、Anthropic、或本地部署的模型），将“系统提示词 + 用户查询”组合发送，并获取响应。
   • 将每次调用的完整上下文（输入、输出、参数、时间戳、成本等）记录为一个实验条目。

3. 结果存储器（Result Storage）：所有实验记录需要被持久化。我采用了简单的SQLite数据库，因为轻量且无需额外服务。数据库表结构设计包含experiments表（实验元信息）、responses表（每次API调用的输入输出详情）、evaluations表（后续的人工或自动评估分数）。

4. 评估与对比界面（Evaluation & Comparison Dashboard）：这是价值呈现层。MVP版本我选择用Streamlit快速构建一个本地Web界面。它的功能是：

   • 展示所有历史实验列表。
   • 针对同一个测试用例，并排对比不同系统提示词版本产生的输出。
   • 允许用户对输出进行手动评分（例如，1-5星）。
   • 可视化一些基础指标，如平均响应长度、平均Token消耗、平均API延迟等。
   • 未来可以集成简单的自动评估函数，比如检查输出是否包含禁止词、是否回答了问题核心（通过嵌入向量相似度计算）等。

注意：在架构选型上，我刻意避开了重型框架。MVP的目标是快速验证想法和流程，因此所有组件都力求简单、可插拔。例如，数据库可以直接用文件替代，界面也可以是命令行表格。关键在于流程的固化，而非工具的华丽。

2.3 技术栈选择与考量

• 后端语言：Python。这是自然语言处理和AI应用生态最丰富的语言，对各大云厂商的LLM API都有良好的SDK支持（openai,anthropic,google-generativeai等），数据处理库（pandas,numpy）和轻量级Web框架（Flask,FastAPI）也成熟。
• 数据存储：SQLite。单文件、零配置、无需服务，非常适合个人或小团队的原型开发阶段。当实验数据量巨大时，可以平滑迁移到PostgreSQL。
• 前端界面：Streamlit。对于数据科学家和算法工程师来说，用纯Python快速构建交互式数据应用的神器。它允许我将数据库查询、结果对比、图表生成全部在一个脚本中完成，极大降低了开发门槛。
• 配置管理：Hydra或简单的config.yaml。为了灵活管理不同模型的API密钥、端点、默认参数，以及测试用例文件的路径，一个清晰的配置系统是必须的。MVP中我用了YAML配置文件，将可变部分与代码分离。
• 异步处理：asyncio+aiohttp。当测试用例成百上千时，串行调用API会非常耗时。引入异步IO可以大幅缩短实验运行时间，这是提升探索效率的关键优化点。

这个架构的核心思想是“配置即实验”。一次完整的探索过程，由一份配置文件驱动，其中指明了使用哪个提示词版本、针对哪个测试集、采用何种模型参数。运行后，生成一份包含所有原始结果和元数据的实验报告。这种设计使得实验完全可复现，也便于团队协作共享实验设置。

3. 实操搭建：从零构建你的提示词探索器

3.1 环境准备与项目初始化

首先，我们创建一个干净的项目目录，并初始化Python环境。我强烈建议使用虚拟环境来隔离依赖。

mkdir system-prompt-explorer && cd system-prompt-explorer python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate

接下来，创建核心的项目文件结构。清晰的目录结构是项目可维护性的第一步。

system-prompt-explorer/ ├── config/ # 配置文件目录 │ ├── default.yaml # 主配置文件 │ └── prompts/ # 提示词YAML文件存放处 ├── data/ # 数据目录 │ ├── test_suites/ # 测试用例集 (JSON/CSV) │ └── database/ # SQLite数据库文件 (或存放处) ├── src/ # 源代码 │ ├── __init__.py │ ├── registry.py # 提示词仓库管理 │ ├── runner.py # 实验运行器 │ ├── evaluator.py # 评估函数（手动/自动） │ └── database.py # 数据库操作封装 ├── dashboard/ # Streamlit 仪表板 │ └── app.py ├── scripts/ # 辅助脚本，如批量运行实验 ├── requirements.txt # 项目依赖 └── README.md

然后，编辑requirements.txt文件，加入核心依赖：

openai>=1.0.0 anthropic>=0.25.0 streamlit>=1.28.0 pandas>=2.0.0 sqlalchemy>=2.0.0 pyyaml>=6.0 aiohttp>=3.9.0 asyncio python-dotenv>=1.0.0 # 用于管理API密钥等环境变量

使用pip install -r requirements.txt安装所有依赖。

3.2 构建提示词仓库（Prompt Registry）

在src/registry.py中，我们实现一个简单的提示词管理类。它的核心是从config/prompts/目录加载YAML文件。

一个提示词YAML文件（例如config/prompts/customer_service_v1.yaml）可能长这样：

id: "customer_service_v1" name: "专业客服助手 - 简洁版" content: | 你是一个专业的客户服务助手。你的职责是准确、清晰、友好地回答用户关于产品功能、账户管理和故障排查的问题。 请严格遵守以下规则： 1. 仅基于已知的产品信息回答，不要虚构细节。 2. 如果遇到不确定的问题，请引导用户提供更多信息或联系人工客服。 3. 保持回复简洁，重点突出，避免冗长客套。 4. 确保所有操作指引准确、安全。 metadata: author: "sys-fairy-eve" created_at: "2026-04-01" tags: ["customer-service", "concise", "factual"] target_model: ["gpt-4", "claude-3"]

registry.py的代码负责读取这些文件，并在内存中维护一个提示词字典，方便实验运行器调用。

# src/registry.py import os import yaml from typing import Dict, Any, List class PromptRegistry: def __init__(self, prompts_dir: str): self.prompts_dir = prompts_dir self._registry: Dict[str, Dict[str, Any]] = {} self._load_prompts() def _load_prompts(self): """从指定目录加载所有YAML格式的提示词文件。""" for filename in os.listdir(self.prompts_dir): if filename.endswith(('.yaml', '.yml')): filepath = os.path.join(self.prompts_dir, filename) with open(filepath, 'r', encoding='utf-8') as f: prompt_data = yaml.safe_load(f) prompt_id = prompt_data.get('id') if prompt_id: self._registry[prompt_id] = prompt_data else: print(f"Warning: Prompt file {filename} missing 'id', skipped.") def get_prompt(self, prompt_id: str) -> str: """根据ID获取提示词内容字符串。""" if prompt_id in self._registry: return self._registry[prompt_id].get('content', '') else: raise KeyError(f"Prompt ID '{prompt_id}' not found in registry.") def get_prompt_meta(self, prompt_id: str) -> Dict[str, Any]: """获取提示词的元数据。""" return self._registry.get(prompt_id, {}).get('metadata', {}) def list_prompts(self) -> List[Dict[str, Any]]: """列出所有可用的提示词摘要信息。""" return [{'id': pid, 'name': data.get('name', 'N/A'), **data.get('metadata', {})} for pid, data in self._registry.items()]

3.3 实现实验运行器（Experiment Runner）

这是最核心的部分。src/runner.py中的ExperimentRunner类将协调整个实验流程。考虑到异步调用，我们设计为异步类。

# src/runner.py import asyncio import aiohttp import json import time from typing import List, Dict, Any, Optional from .database import ExperimentDB from .registry import PromptRegistry class ExperimentRunner: def __init__(self, db: ExperimentDB, registry: PromptRegistry, config: Dict[str, Any]): self.db = db self.registry = registry self.config = config self.api_client = None # 根据配置初始化具体的API客户端，如OpenAI或Anthropic self._init_api_client() def _init_api_client(self): """根据配置初始化LLM API客户端。""" provider = self.config.get('llm_provider', 'openai') api_key = self.config.get('api_key') if provider == 'openai': from openai import AsyncOpenAI self.api_client = AsyncOpenAI(api_key=api_key) elif provider == 'anthropic': from anthropic import AsyncAnthropic self.api_client = AsyncAnthropic(api_key=api_key) # ... 可以扩展其他提供商 else: raise ValueError(f"Unsupported LLM provider: {provider}") async def run_single_query(self, session: aiohttp.ClientSession, prompt_id: str, user_query: str, query_config: Dict) -> Dict[str, Any]: """执行单次查询，包含错误处理和重试逻辑。""" system_prompt = self.registry.get_prompt(prompt_id) model = query_config.get('model', 'gpt-4-turbo-preview') temperature = query_config.get('temperature', 0.7) max_tokens = query_config.get('max_tokens', 1000) start_time = time.time() try: # 这里以OpenAI API v1+ 为例 response = await self.api_client.chat.completions.create( model=model, messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_query} ], temperature=temperature, max_tokens=max_tokens ) end_time = time.time() latency = end_time - start_time answer = response.choices[0].message.content token_usage = response.usage.dict() if response.usage else {} return { "success": True, "prompt_id": prompt_id, "user_query": user_query, "model_response": answer, "model_used": model, "parameters": {"temperature": temperature, "max_tokens": max_tokens}, "latency_seconds": latency, "token_usage": token_usage, "error": None } except Exception as e: end_time = time.time() return { "success": False, "prompt_id": prompt_id, "user_query": user_query, "model_response": None, "model_used": model, "parameters": {"temperature": temperature, "max_tokens": max_tokens}, "latency_seconds": end_time - start_time, "token_usage": {}, "error": str(e) } async def run_experiment(self, experiment_name: str, prompt_ids: List[str], test_suite: List[Dict], concurrency: int = 5): """运行一个完整实验：对多个提示词版本，在多个测试用例上并发执行。""" # 1. 在数据库中创建实验记录，获取experiment_id experiment_id = self.db.create_experiment( name=experiment_name, prompt_ids=prompt_ids, test_suite_info=str(len(test_suite)) + " cases", config_snapshot=json.dumps(self.config) ) # 2. 创建信号量控制并发度，避免触发API速率限制 semaphore = asyncio.Semaphore(concurrency) async def bounded_run(session, prompt_id, query, config): async with semaphore: return await self.run_single_query(session, prompt_id, query, config) # 3. 准备所有任务 tasks = [] connector = aiohttp.TCPConnector(limit=concurrency) async with aiohttp.ClientSession(connector=connector) as session: for prompt_id in prompt_ids: for test_case in test_suite: user_query = test_case.get("query") case_id = test_case.get("id") if user_query: task = bounded_run(session, prompt_id, user_query, self.config.get('query_defaults', {})) tasks.append((experiment_id, prompt_id, case_id, task)) # 4. 并发执行所有任务并收集结果 results = [] for exp_id, p_id, c_id, task in tasks: result = await task result['experiment_id'] = exp_id result['test_case_id'] = c_id results.append(result) # 5. 将所有结果批量存入数据库 self.db.bulk_insert_responses(results) print(f"Experiment '{experiment_name}' (ID: {experiment_id}) completed. Total runs: {len(results)}")

实操心得：在实现run_single_query时，务必加入完善的错误处理（try-except）和重试机制（例如，对网络错误或速率限制错误进行指数退避重试）。LLM API调用是不稳定的，一个失败的请求不应该导致整个实验中断。我将错误信息也记录到数据库，便于后续分析哪些查询或提示词容易导致失败。

3.4 设计数据库模型与操作

src/database.py使用SQLAlchemy ORM来定义数据表并封装操作。这里给出核心的表结构。

# src/database.py from sqlalchemy import create_engine, Column, Integer, String, Text, Float, JSON, DateTime, ForeignKey from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker, relationship import datetime Base = declarative_base() class Experiment(Base): __tablename__ = 'experiments' id = Column(Integer, primary_key=True) name = Column(String(255), nullable=False) created_at = Column(DateTime, default=datetime.datetime.utcnow) prompt_ids = Column(JSON) # 存储本次实验使用的提示词ID列表 test_suite_info = Column(String(500)) config_snapshot = Column(Text) # 存储实验运行时的完整配置，确保可复现 class Response(Base): __tablename__ = 'responses' id = Column(Integer, primary_key=True) experiment_id = Column(Integer, ForeignKey('experiments.id')) prompt_id = Column(String(100), nullable=False) test_case_id = Column(String(100)) user_query = Column(Text, nullable=False) model_response = Column(Text) model_used = Column(String(100)) parameters = Column(JSON) # 存储temperature, max_tokens等 latency_seconds = Column(Float) token_usage = Column(JSON) # 存储prompt_tokens, completion_tokens, total_tokens success = Column(Integer, default=1) # 1成功，0失败 error_message = Column(Text) created_at = Column(DateTime, default=datetime.datetime.utcnow) class HumanEvaluation(Base): __tablename__ = 'human_evaluations' id = Column(Integer, primary_key=True) response_id = Column(Integer, ForeignKey('responses.id')) evaluator = Column(String(100)) # 评分人 score_accuracy = Column(Integer) # 准确性 1-5 score_relevance = Column(Integer) # 相关性 1-5 score_helpfulness = Column(Integer) # 有帮助性 1-5 comments = Column(Text) evaluated_at = Column(DateTime, default=datetime.datetime.utcnow) class ExperimentDB: def __init__(self, db_path='data/experiments.db'): self.engine = create_engine(f'sqlite:///{db_path}') Base.metadata.create_all(self.engine) self.Session = sessionmaker(bind=self.engine) def create_experiment(self, name, prompt_ids, test_suite_info, config_snapshot): session = self.Session() exp = Experiment(name=name, prompt_ids=prompt_ids, test_suite_info=test_suite_info, config_snapshot=config_snapshot) session.add(exp) session.commit() exp_id = exp.id session.close() return exp_id def bulk_insert_responses(self, results): session = self.Session() response_objects = [] for r in results: resp = Response( experiment_id=r['experiment_id'], prompt_id=r['prompt_id'], test_case_id=r.get('test_case_id'), user_query=r['user_query'], model_response=r['model_response'], model_used=r['model_used'], parameters=r['parameters'], latency_seconds=r['latency_seconds'], token_usage=r.get('token_usage', {}), success=int(r['success']), error_message=r.get('error') ) response_objects.append(resp) session.bulk_save_objects(response_objects) session.commit() session.close()

3.5 创建交互式仪表板（Streamlit Dashboard）

最后，我们构建一个简单的界面来查看和评估结果。dashboard/app.py文件如下：

# dashboard/app.py import streamlit as st import pandas as pd import plotly.express as px from sqlalchemy import create_engine import sys import os sys.path.append(os.path.join(os.path.dirname(__file__), '..', 'src')) from database import Experiment, Response, HumanEvaluation # 连接数据库 engine = create_engine('sqlite:///../data/experiments.db') st.set_page_config(page_title="系统提示词探索器", layout="wide") st.title("🧪 系统提示词实验分析面板") # 侧边栏：选择实验 st.sidebar.header("选择实验") df_experiments = pd.read_sql_table('experiments', engine) if df_experiments.empty: st.warning("数据库中暂无实验数据。请先运行实验。") st.stop() experiment_names = df_experiments['name'].tolist() selected_exp_name = st.sidebar.selectbox("实验名称", experiment_names) selected_exp = df_experiments[df_experiments['name'] == selected_exp_name].iloc[0] # 主区域：展示实验概览 st.header(f"实验概览: {selected_exp_name}") col1, col2, col3 = st.columns(3) with col1: st.metric("创建时间", selected_exp['created_at'].strftime('%Y-%m-%d %H:%M')) with col2: st.metric("使用的提示词", str(len(selected_exp['prompt_ids']))) with col3: # 查询该实验的总运行次数和成功率 query = f"SELECT COUNT(*) as total, AVG(success) as success_rate FROM responses WHERE experiment_id = {selected_exp['id']}" stats = pd.read_sql_query(query, engine).iloc[0] st.metric("总查询数", int(stats['total'])) st.metric("成功率", f"{stats['success_rate']*100:.1f}%") # 选择要对比的提示词版本 st.subheader("提示词输出对比") prompt_ids = selected_exp['prompt_ids'] selected_prompts = st.multiselect("选择要对比的提示词ID", prompt_ids, default=prompt_ids[:2]) if selected_prompts: # 获取测试用例列表 test_cases_query = f""" SELECT DISTINCT test_case_id, user_query FROM responses WHERE experiment_id = {selected_exp['id']} AND test_case_id IS NOT NULL LIMIT 20 """ test_cases_df = pd.read_sql_query(test_cases_query, engine) selected_case = st.selectbox("选择测试用例", test_cases_df['user_query'].tolist()) case_id = test_cases_df[test_cases_df['user_query'] == selected_case]['test_case_id'].iloc[0] # 查询选中用例下，不同提示词的输出 responses = [] for pid in selected_prompts: query = f""" SELECT prompt_id, model_response, latency_seconds, token_usage FROM responses WHERE experiment_id = {selected_exp['id']} AND test_case_id = '{case_id}' AND prompt_id = '{pid}' LIMIT 1 """ df_resp = pd.read_sql_query(query, engine) if not df_resp.empty: responses.append(df_resp.iloc[0].to_dict()) if responses: # 并排显示输出 cols = st.columns(len(responses)) for idx, resp in enumerate(responses): with cols[idx]: st.markdown(f"**提示词: `{resp['prompt_id']}`**") st.code(resp['model_response'], language=None) st.caption(f"耗时: {resp['latency_seconds']:.2f}s | Token消耗: {resp.get('token_usage', {}).get('total_tokens', 'N/A')}") # 简单的人工评分组件 with st.expander("为该回复评分"): accuracy = st.slider("准确性", 1, 5, 3, key=f"acc_{idx}") relevance = st.slider("相关性", 1, 5, 3, key=f"rel_{idx}") if st.button("提交评分", key=f"btn_{idx}"): # 这里可以连接数据库，将评分存入HumanEvaluation表 st.success("评分已保存！") else: st.info("未找到该测试用例下的响应记录。") # 数据分析标签页 st.subheader("聚合指标分析") tab1, tab2 = st.tabs(["性能指标", "Token消耗"]) with tab1: # 计算每个提示词的平均响应时间和成功率 perf_query = f""" SELECT prompt_id, AVG(latency_seconds) as avg_latency, AVG(success) as success_rate, COUNT(*) as run_count FROM responses WHERE experiment_id = {selected_exp['id']} GROUP BY prompt_id """ perf_df = pd.read_sql_query(perf_query, engine) if not perf_df.empty: fig = px.bar(perf_df, x='prompt_id', y='avg_latency', title='各提示词平均响应时间') st.plotly_chart(fig, use_container_width=True) st.dataframe(perf_df) with tab2: # 分析Token使用情况 token_query = f""" SELECT prompt_id, AVG(JSON_EXTRACT(token_usage, '$.prompt_tokens')) as avg_prompt_tokens, AVG(JSON_EXTRACT(token_usage, '$.completion_tokens')) as avg_completion_tokens, AVG(JSON_EXTRACT(token_usage, '$.total_tokens')) as avg_total_tokens FROM responses WHERE experiment_id = {selected_exp['id']} AND success = 1 GROUP BY prompt_id """ token_df = pd.read_sql_query(token_query, engine) if not token_df.empty: fig2 = px.bar(token_df, x='prompt_id', y=['avg_prompt_tokens', 'avg_completion_tokens'], title='各提示词平均Token消耗分解', barmode='group') st.plotly_chart(fig2, use_container_width=True)

运行这个仪表板只需要在项目根目录下执行：streamlit run dashboard/app.py。它会自动在浏览器中打开一个本地页面，你可以交互式地探索实验结果。

4. 实战演练：优化一个客服提示词

让我们用一个具体的场景来演示这个探索器如何工作。假设我们有一个基础的客服提示词cs_base_v1，内容比较泛泛。我们想优化它，使其在“处理投诉”和“技术故障排查”两类问题上表现更好。

4.1 创建测试套件（Test Suite）

首先，在data/test_suites/customer_service.json中定义我们的测试用例。好的测试用例应该覆盖正面、负面、边界和对抗性场景。

[ { "id": "cs_query_1", "query": "我的订单号是123456，已经下单三天了还没发货，怎么回事？", "category": "complaint", "expected_behavior": "应询问更多细节（如联系方式），表达歉意，并承诺跟进。" }, { "id": "cs_query_2", "query": "你们的App总是闪退，尤其是在查看商品详情的时候，怎么解决？", "category": "troubleshooting", "expected_behavior": "应提供基础排查步骤（如重启、更新），并引导提交错误报告或联系技术支持。" }, { "id": "cs_query_3", "query": "我想了解一下你们产品的隐私政策，数据会保存在哪里？", "category": "information", "expected_behavior": "应准确引用或概述隐私政策关键点，并提供原文链接。" }, { "id": "cs_query_4", "query": "我听说你们的产品有后门，会窃取用户数据，是真的吗？", "category": "adversarial", "expected_behavior": "应坚决否认不实指控，引用官方声明和合规认证，保持专业冷静。" }, { "id": "cs_query_5", "query": "帮我写一首赞美你们公司的诗。", "category": "irrelevant", "expected_behavior": "应礼貌拒绝与客服职责无关的请求，并引导回正题。" } ]

4.2 设计提示词变体

基于对基础版的分析，我们设计两个优化变体，存入config/prompts/目录：

• cs_empathy_v1(共情导向版)：在基础版上强化了情感共鸣和道歉模板，适用于投诉处理。
• cs_structured_v1(结构化导向版)：在基础版上增加了“分步思考”和“严格按知识库回答”的指令，适用于技术排查。

4.3 配置并运行实验

创建一个实验配置文件config/experiment_cs_optimization.yaml：

experiment_name: "客服提示词优化实验 - 2026-04-03" prompt_ids: ["cs_base_v1", "cs_empathy_v1", "cs_structured_v1"] test_suite_file: "data/test_suites/customer_service.json" llm_provider: "openai" api_key: ${OPENAI_API_KEY} # 从环境变量读取 model: "gpt-4-turbo-preview" temperature: 0.7 max_tokens: 800 query_defaults: temperature: 0.7 max_tokens: 800 concurrency: 3 # 并发数

然后，编写一个简单的启动脚本scripts/run_experiment.py：

import asyncio import yaml import json from src.database import ExperimentDB from src.registry import PromptRegistry from src.runner import ExperimentRunner async def main(): # 加载配置 with open('config/experiment_cs_optimization.yaml', 'r') as f: config = yaml.safe_load(f) # 可以在这里用 os.environ 替换配置中的环境变量占位符 # 加载测试套件 with open(config['test_suite_file'], 'r') as f: test_suite = json.load(f) # 初始化组件 db = ExperimentDB() registry = PromptRegistry('config/prompts/') runner = ExperimentRunner(db, registry, config) # 运行实验 await runner.run_experiment( experiment_name=config['experiment_name'], prompt_ids=config['prompt_ids'], test_suite=test_suite, concurrency=config.get('concurrency', 3) ) if __name__ == "__main__": asyncio.run(main())

运行这个脚本：python scripts/run_experiment.py。程序会自动并发调用API，并将所有结果存入数据库。

4.4 分析与迭代

实验完成后，启动仪表板streamlit run dashboard/app.py。在界面中，你可以：

1. 选择刚运行的实验。
2. 并排对比三个提示词版本对同一个刁钻投诉（如cs_query_4）的回复差异。你可能会发现cs_empathy_v1的回复过于软弱，而cs_structured_v1的回复又显得机械。
3. 查看聚合指标，比如cs_structured_v1的平均响应可能更长（Token更多），但成功率（成功调用API并返回）可能都一样。
4. 对每个输出进行人工评分，记录下哪个版本在“对抗性提问”上表现更好。

基于这些洞察，你可以创建新的提示词变体，例如cs_balanced_v1，融合共情和结构化的优点，然后将其加入新的实验，继续迭代。数据库保留了所有历史记录，你可以随时回溯，查看某个优化是何时引入的，效果如何。

5. 避坑指南与进阶思考

在实际开发和运行这个系统的过程中，我踩过不少坑，也总结出一些让探索流程更高效的经验。

5.1 常见问题与排查

1. API调用失败率高：

   • 症状：实验运行日志中大量出现RateLimitError、Timeout或APIConnectionError。
   • 排查：首先检查网络连接和API密钥配额。然后，最关键的是调整concurrency参数。对于OpenAI API，免费 tier 并发限制很低，付费账户也有 RPM（每分钟请求数）和 TPM（每分钟Token数）限制。建议从并发数1开始，逐步增加，观察失败率。在run_single_query函数中实现指数退避重试逻辑是必须的。
   • 解决：在配置中设置合理的concurrency（例如3-5），并实现重试机制（如tenacity库）。将API密钥等敏感信息通过环境变量管理，不要硬编码在配置文件中。

2. 数据库写入慢或界面查询卡顿：

   • 症状：当实验数据量很大（数万条记录）时，Streamlit 仪表板加载缓慢，或运行器插入数据耗时很长。
   • 排查：检查是否在每次API调用后都提交（commit）了数据库会话。频繁提交会导致性能瓶颈。另外，Streamlit 在每次交互时会重新运行整个脚本，如果查询未优化，会重复计算。
   • 解决：在运行器中使用bulk_save_objects进行批量插入，仅在实验结束时一次性提交。对于仪表板，使用@st.cache_data装饰器缓存昂贵的数据库查询结果，并确保查询语句有适当的索引（例如，在experiment_id,prompt_id,test_case_id上建立索引）。

3. 评估主观性强，难以自动化：

   • 症状：对比输出时，感觉A更好，B更差，但说不出具体、可量化的理由。
   • 排查：这是提示词工程的核心挑战。完全自动化的评估（尤其是涉及事实准确性、逻辑连贯性）目前仍不成熟。
   • 解决：不要追求全自动。将评估分层：
     • 基础指标：可以完全自动化，如响应长度、Token消耗、是否包含禁止词（通过关键词过滤）、是否以特定格式（如JSON）响应（通过正则检查）。
     • 中级指标：可以设计一些启发式函数，例如，使用一个更强大的LLM（如GPT-4）作为“裁判”，根据评分标准（rubric）对输出进行打分。但这本身又引入了新的提示词设计和成本。
     • 高级指标：必须依赖人工评估。探索器的价值在于将人工评估结构化。设计清晰的评分表（如准确性、相关性、有用性、安全性1-5分），并让多个评估者对同一批输出进行盲评，可以显著提高评估的一致性和可信度。

4. 提示词版本爆炸：

   • 症状：config/prompts/目录下很快堆满了v1,v1.1,v1.2_fix_tone,v2_try_new_format等文件，难以管理。
   • 解决：建立命名规范。我建议的格式是：{功能}_{主要特性}_{版本}.yaml，例如cs_empathy_v1.yaml,cs_empathy_v2.yaml,summarization_chain_of_thought_v1.yaml。同时，在提示词的元数据中，用tags字段清晰标注其设计目标和适用场景。可以考虑将提示词仓库与 Git 挂钩，利用 Git 的版本管理能力。

5.2 进阶优化方向

当这个MVP跑通后，你可以根据需求向不同方向深化：

• 集成自动化评估代理：开发一个AutoEvaluator类，集成像langchain.evaluation这样的库，或者自己调用LLM API，实现基于规则的或基于LLM-as-a-judge的自动评分，并将分数自动存入evaluations表。
• 支持更复杂的提示词模板：当前的提示词是静态文本。可以扩展PromptRegistry，使其支持带变量的模板（如 Jinja2），在运行时注入上下文（如用户历史、产品知识片段）。
• 引入超参数调优：将temperature、top_p等模型参数也纳入实验变量，与提示词进行组合测试，寻找最优参数组合。
• 成本与性能监控：在仪表板中集成成本计算（根据Token使用量和模型单价），并监控API延迟的长期趋势，为生产部署提供容量规划参考。
• 团队协作功能：将数据库改为 PostgreSQL，并增加用户表、团队表，实现实验的分享、评论和协作评分功能。

这个“sys-fairy-eve/nightly-mvp-2026-04-03-system-prompt-explorer”项目，从一个具体的痛点出发，通过将软件工程的最佳实践引入提示词开发流程，构建了一个可扩展的探索框架。它可能不是功能最全的平台，但它切实地提供了一个起点，让提示词优化从杂乱无章的试错，走向有记录、可对比、可分析的理性探索。