793 lines
23 KiB
Markdown
793 lines
23 KiB
Markdown
|
# 意图驱动话术流程 - 设计文档
|
|||
|
|
|
|||
|
|
## 1. 架构概览
|
|||
|
|
|
|||
|
|
### 1.1 系统架构图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 前端配置界面 │
|
|||
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|||
|
|
│ │ 模式选择器 │ │ 意图配置表单 │ │ 约束管理器 │ │
|
|||
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────┘
|
|||
|
|
│ HTTP API
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 后端 API 层 │
|
|||
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ ScriptFlowService (CRUD) │ │
|
|||
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────┐
|
|||
|
|
│ FlowEngine (执行引擎) │
|
|||
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ start() / advance() │ │
|
|||
|
|
│ │ ↓ │ │
|
|||
|
|
│ │ _generate_step_content() ← 核心扩展点 │ │
|
|||
|
|
│ │ ├─ fixed: 返回 content │ │
|
|||
|
|
│ │ ├─ flexible: 调用 ScriptGenerator │ │
|
|||
|
|
│ │ └─ template: 调用 TemplateEngine │ │
|
|||
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
┌───────────────┼───────────────┐
|
|||
|
|
▼ ▼ ▼
|
|||
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|||
|
|
│ScriptGenerator│ │TemplateEngine│ │ Orchestrator │
|
|||
|
|
│ (新增) │ │ (新增) │ │ (LLM调用) │
|
|||
|
|
└──────────────┘ └──────────────┘ └──────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 1.2 数据流图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
用户配置流程
|
|||
|
|
│
|
|||
|
|
├─ 选择 script_mode
|
|||
|
|
│ ├─ fixed: 配置 content
|
|||
|
|
│ ├─ flexible: 配置 intent + constraints
|
|||
|
|
│ └─ template: 配置 content (模板)
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
保存到数据库 (ScriptFlow.steps JSON)
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
执行时加载流程
|
|||
|
|
│
|
|||
|
|
├─ FlowEngine.start() / advance()
|
|||
|
|
│ │
|
|||
|
|
│ ├─ 获取当前步骤配置
|
|||
|
|
│ │
|
|||
|
|
│ ├─ 调用 _generate_step_content()
|
|||
|
|
│ │ │
|
|||
|
|
│ │ ├─ fixed: 直接返回 content
|
|||
|
|
│ │ │
|
|||
|
|
│ │ ├─ flexible:
|
|||
|
|
│ │ │ ├─ 构建 Prompt (intent + constraints + history)
|
|||
|
|
│ │ │ ├─ 调用 LLM 生成话术
|
|||
|
|
│ │ │ └─ 失败时返回 fallback (content)
|
|||
|
|
│ │ │
|
|||
|
|
│ │ └─ template:
|
|||
|
|
│ │ ├─ 解析模板变量
|
|||
|
|
│ │ ├─ 调用 LLM 生成变量值
|
|||
|
|
│ │ └─ 替换模板占位符
|
|||
|
|
│ │
|
|||
|
|
│ └─ 返回生成的话术
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
返回给用户
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 核心模块设计
|
|||
|
|
|
|||
|
|
### 2.1 后端：话术生成引擎
|
|||
|
|
|
|||
|
|
#### 2.1.1 FlowEngine 扩展
|
|||
|
|
|
|||
|
|
**文件位置**: `ai-service/app/services/flow/engine.py`
|
|||
|
|
|
|||
|
|
**新增方法**:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
async def _generate_step_content(
|
|||
|
|
self,
|
|||
|
|
step: dict,
|
|||
|
|
context: dict,
|
|||
|
|
history: list[dict]
|
|||
|
|
) -> str:
|
|||
|
|
"""
|
|||
|
|
[AC-IDS-03] 根据步骤配置生成话术内容
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
step: 步骤配置 (包含 script_mode, intent, constraints 等)
|
|||
|
|
context: 会话上下文 (从 FlowInstance.context 获取)
|
|||
|
|
history: 对话历史 (最近 N 轮)
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
生成的话术文本
|
|||
|
|
"""
|
|||
|
|
script_mode = step.get("script_mode", "fixed")
|
|||
|
|
|
|||
|
|
if script_mode == "fixed":
|
|||
|
|
return step.get("content", "")
|
|||
|
|
|
|||
|
|
elif script_mode == "flexible":
|
|||
|
|
return await self._generate_flexible_script(step, context, history)
|
|||
|
|
|
|||
|
|
elif script_mode == "template":
|
|||
|
|
return await self._generate_template_script(step, context, history)
|
|||
|
|
|
|||
|
|
else:
|
|||
|
|
logger.warning(f"Unknown script_mode: {script_mode}, fallback to fixed")
|
|||
|
|
return step.get("content", "")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**修改方法**:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
async def start(
|
|||
|
|
self,
|
|||
|
|
tenant_id: str,
|
|||
|
|
session_id: str,
|
|||
|
|
flow_id: uuid.UUID,
|
|||
|
|
) -> tuple[FlowInstance | None, str | None]:
|
|||
|
|
"""
|
|||
|
|
[AC-IDS-05] 修改：启动流程时生成首步话术
|
|||
|
|
"""
|
|||
|
|
# ... 现有逻辑 ...
|
|||
|
|
|
|||
|
|
first_step = flow.steps[0]
|
|||
|
|
|
|||
|
|
# 修改：调用话术生成引擎
|
|||
|
|
history = await self._get_conversation_history(tenant_id, session_id, limit=3)
|
|||
|
|
first_content = await self._generate_step_content(
|
|||
|
|
first_step,
|
|||
|
|
instance.context,
|
|||
|
|
history
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
return instance, first_content
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2.1.2 ScriptGenerator (新增模块)
|
|||
|
|
|
|||
|
|
**文件位置**: `ai-service/app/services/flow/script_generator.py`
|
|||
|
|
|
|||
|
|
**职责**: 灵活模式的话术生成逻辑
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class ScriptGenerator:
|
|||
|
|
"""
|
|||
|
|
[AC-IDS-04] 灵活模式话术生成器
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
def __init__(self, orchestrator):
|
|||
|
|
self._orchestrator = orchestrator
|
|||
|
|
|
|||
|
|
async def generate(
|
|||
|
|
self,
|
|||
|
|
intent: str,
|
|||
|
|
intent_description: str | None,
|
|||
|
|
constraints: list[str],
|
|||
|
|
context: dict,
|
|||
|
|
history: list[dict],
|
|||
|
|
fallback: str
|
|||
|
|
) -> str:
|
|||
|
|
"""
|
|||
|
|
生成灵活话术
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
intent: 步骤意图
|
|||
|
|
intent_description: 意图详细说明
|
|||
|
|
constraints: 话术约束条件
|
|||
|
|
context: 会话上下文
|
|||
|
|
history: 对话历史
|
|||
|
|
fallback: 失败时的 fallback 话术
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
生成的话术文本
|
|||
|
|
"""
|
|||
|
|
try:
|
|||
|
|
prompt = self._build_prompt(
|
|||
|
|
intent, intent_description, constraints, context, history
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
# 调用 LLM，设置 2 秒超时
|
|||
|
|
response = await asyncio.wait_for(
|
|||
|
|
self._orchestrator.generate(prompt),
|
|||
|
|
timeout=2.0
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
return response.strip()
|
|||
|
|
|
|||
|
|
except asyncio.TimeoutError:
|
|||
|
|
logger.warning(f"[AC-IDS-05] Script generation timeout, use fallback")
|
|||
|
|
return fallback
|
|||
|
|
|
|||
|
|
except Exception as e:
|
|||
|
|
logger.error(f"[AC-IDS-05] Script generation failed: {e}, use fallback")
|
|||
|
|
return fallback
|
|||
|
|
|
|||
|
|
def _build_prompt(
|
|||
|
|
self,
|
|||
|
|
intent: str,
|
|||
|
|
intent_description: str | None,
|
|||
|
|
constraints: list[str],
|
|||
|
|
context: dict,
|
|||
|
|
history: list[dict]
|
|||
|
|
) -> str:
|
|||
|
|
"""
|
|||
|
|
[AC-IDS-04] 构建 LLM Prompt
|
|||
|
|
"""
|
|||
|
|
prompt_parts = [
|
|||
|
|
"你是一个客服对话系统，当前需要执行以下步骤：",
|
|||
|
|
"",
|
|||
|
|
f"【步骤目标】{intent}"
|
|||
|
|
]
|
|||
|
|
|
|||
|
|
if intent_description:
|
|||
|
|
prompt_parts.append(f"【详细说明】{intent_description}")
|
|||
|
|
|
|||
|
|
if constraints:
|
|||
|
|
prompt_parts.append("【约束条件】")
|
|||
|
|
for c in constraints:
|
|||
|
|
prompt_parts.append(f"- {c}")
|
|||
|
|
|
|||
|
|
if history:
|
|||
|
|
prompt_parts.append("")
|
|||
|
|
prompt_parts.append("【对话历史】")
|
|||
|
|
for msg in history[-3:]: # 最近 3 轮
|
|||
|
|
role = "用户" if msg["role"] == "user" else "客服"
|
|||
|
|
prompt_parts.append(f"{role}: {msg['content']}")
|
|||
|
|
|
|||
|
|
if context.get("inputs"):
|
|||
|
|
prompt_parts.append("")
|
|||
|
|
prompt_parts.append("【已收集信息】")
|
|||
|
|
for inp in context["inputs"]:
|
|||
|
|
prompt_parts.append(f"- {inp}")
|
|||
|
|
|
|||
|
|
prompt_parts.extend([
|
|||
|
|
"",
|
|||
|
|
"请生成一句符合目标和约束的话术（不超过50字）。",
|
|||
|
|
"只返回话术内容，不要解释。"
|
|||
|
|
])
|
|||
|
|
|
|||
|
|
return "\n".join(prompt_parts)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2.1.3 TemplateEngine (新增模块)
|
|||
|
|
|
|||
|
|
**文件位置**: `ai-service/app/services/flow/template_engine.py`
|
|||
|
|
|
|||
|
|
**职责**: 模板模式的变量填充逻辑
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
import re
|
|||
|
|
|
|||
|
|
class TemplateEngine:
|
|||
|
|
"""
|
|||
|
|
[AC-IDS-06] 模板话术引擎
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
VARIABLE_PATTERN = re.compile(r'\{(\w+)\}')
|
|||
|
|
|
|||
|
|
def __init__(self, orchestrator):
|
|||
|
|
self._orchestrator = orchestrator
|
|||
|
|
|
|||
|
|
async def fill_template(
|
|||
|
|
self,
|
|||
|
|
template: str,
|
|||
|
|
context: dict,
|
|||
|
|
history: list[dict]
|
|||
|
|
) -> str:
|
|||
|
|
"""
|
|||
|
|
填充模板变量
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
template: 话术模板（包含 {变量名} 占位符）
|
|||
|
|
context: 会话上下文
|
|||
|
|
history: 对话历史
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
填充后的话术
|
|||
|
|
"""
|
|||
|
|
# 提取模板中的变量
|
|||
|
|
variables = self.VARIABLE_PATTERN.findall(template)
|
|||
|
|
|
|||
|
|
if not variables:
|
|||
|
|
return template
|
|||
|
|
|
|||
|
|
# 为每个变量生成值
|
|||
|
|
variable_values = {}
|
|||
|
|
for var in variables:
|
|||
|
|
value = await self._generate_variable_value(var, context, history)
|
|||
|
|
variable_values[var] = value
|
|||
|
|
|
|||
|
|
# 替换模板中的占位符
|
|||
|
|
result = template
|
|||
|
|
for var, value in variable_values.items():
|
|||
|
|
result = result.replace(f"{{{var}}}", value)
|
|||
|
|
|
|||
|
|
return result
|
|||
|
|
|
|||
|
|
async def _generate_variable_value(
|
|||
|
|
self,
|
|||
|
|
variable_name: str,
|
|||
|
|
context: dict,
|
|||
|
|
history: list[dict]
|
|||
|
|
) -> str:
|
|||
|
|
"""
|
|||
|
|
为单个变量生成值
|
|||
|
|
"""
|
|||
|
|
# 先尝试从上下文中获取
|
|||
|
|
if variable_name in context:
|
|||
|
|
return str(context[variable_name])
|
|||
|
|
|
|||
|
|
# 否则调用 LLM 生成
|
|||
|
|
prompt = f"""
|
|||
|
|
根据对话历史，为变量 "{variable_name}" 生成合适的值。
|
|||
|
|
|
|||
|
|
对话历史：
|
|||
|
|
{self._format_history(history[-3:])}
|
|||
|
|
|
|||
|
|
只返回变量值，不要解释。
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
try:
|
|||
|
|
response = await asyncio.wait_for(
|
|||
|
|
self._orchestrator.generate(prompt),
|
|||
|
|
timeout=1.0
|
|||
|
|
)
|
|||
|
|
return response.strip()
|
|||
|
|
except:
|
|||
|
|
return f"[{variable_name}]" # fallback
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2.2 前端：配置界面设计
|
|||
|
|
|
|||
|
|
#### 2.2.1 类型定义扩展
|
|||
|
|
|
|||
|
|
**文件位置**: `ai-service-admin/src/types/script-flow.ts`
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
export type ScriptMode = 'fixed' | 'flexible' | 'template'
|
|||
|
|
|
|||
|
|
export interface FlowStep {
|
|||
|
|
step_id: string
|
|||
|
|
step_no: number
|
|||
|
|
|
|||
|
|
// 原有字段
|
|||
|
|
content: string
|
|||
|
|
wait_input: boolean
|
|||
|
|
timeout_seconds?: number
|
|||
|
|
timeout_action?: 'repeat' | 'skip' | 'transfer'
|
|||
|
|
next_conditions?: NextCondition[]
|
|||
|
|
|
|||
|
|
// 新增字段
|
|||
|
|
script_mode?: ScriptMode
|
|||
|
|
intent?: string
|
|||
|
|
intent_description?: string
|
|||
|
|
script_constraints?: string[]
|
|||
|
|
expected_variables?: string[]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export const SCRIPT_MODE_OPTIONS = [
|
|||
|
|
{ value: 'fixed', label: '固定话术', description: '话术内容固定不变' },
|
|||
|
|
{ value: 'flexible', label: '灵活话术', description: 'AI根据意图和上下文生成' },
|
|||
|
|
{ value: 'template', label: '模板话术', description: 'AI填充模板中的变量' }
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2.2.2 配置表单组件
|
|||
|
|
|
|||
|
|
**文件位置**: `ai-service-admin/src/views/admin/script-flow/index.vue`
|
|||
|
|
|
|||
|
|
**UI 结构**:
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<el-form-item label="话术模式">
|
|||
|
|
<el-radio-group v-model="currentStep.script_mode">
|
|||
|
|
<el-radio-button
|
|||
|
|
v-for="option in SCRIPT_MODE_OPTIONS"
|
|||
|
|
:key="option.value"
|
|||
|
|
:label="option.value"
|
|||
|
|
>
|
|||
|
|
{{ option.label }}
|
|||
|
|
<el-tooltip :content="option.description">
|
|||
|
|
<el-icon><QuestionFilled /></el-icon>
|
|||
|
|
</el-tooltip>
|
|||
|
|
</el-radio-button>
|
|||
|
|
</el-radio-group>
|
|||
|
|
</el-form-item>
|
|||
|
|
|
|||
|
|
<!-- 固定模式 -->
|
|||
|
|
<template v-if="currentStep.script_mode === 'fixed'">
|
|||
|
|
<el-form-item label="话术内容" required>
|
|||
|
|
<el-input
|
|||
|
|
v-model="currentStep.content"
|
|||
|
|
type="textarea"
|
|||
|
|
:rows="3"
|
|||
|
|
placeholder="输入固定话术内容"
|
|||
|
|
/>
|
|||
|
|
</el-form-item>
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<!-- 灵活模式 -->
|
|||
|
|
<template v-if="currentStep.script_mode === 'flexible'">
|
|||
|
|
<el-form-item label="步骤意图" required>
|
|||
|
|
<el-input
|
|||
|
|
v-model="currentStep.intent"
|
|||
|
|
placeholder="例如：获取用户姓名"
|
|||
|
|
/>
|
|||
|
|
</el-form-item>
|
|||
|
|
|
|||
|
|
<el-form-item label="意图说明">
|
|||
|
|
<el-input
|
|||
|
|
v-model="currentStep.intent_description"
|
|||
|
|
type="textarea"
|
|||
|
|
:rows="2"
|
|||
|
|
placeholder="详细描述这一步的目的和期望效果"
|
|||
|
|
/>
|
|||
|
|
</el-form-item>
|
|||
|
|
|
|||
|
|
<el-form-item label="话术约束">
|
|||
|
|
<ConstraintManager v-model="currentStep.script_constraints" />
|
|||
|
|
</el-form-item>
|
|||
|
|
|
|||
|
|
<el-form-item label="Fallback话术" required>
|
|||
|
|
<el-input
|
|||
|
|
v-model="currentStep.content"
|
|||
|
|
type="textarea"
|
|||
|
|
:rows="2"
|
|||
|
|
placeholder="AI生成失败时使用的备用话术"
|
|||
|
|
/>
|
|||
|
|
</el-form-item>
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<!-- 模板模式 -->
|
|||
|
|
<template v-if="currentStep.script_mode === 'template'">
|
|||
|
|
<el-form-item label="话术模板" required>
|
|||
|
|
<el-input
|
|||
|
|
v-model="currentStep.content"
|
|||
|
|
type="textarea"
|
|||
|
|
:rows="3"
|
|||
|
|
placeholder="使用 {变量名} 标记可变部分，例如：您好{user_name}，请问您{inquiry_style}？"
|
|||
|
|
/>
|
|||
|
|
<div class="template-hint">
|
|||
|
|
提示：使用 {变量名} 标记需要AI填充的部分
|
|||
|
|
</div>
|
|||
|
|
</el-form-item>
|
|||
|
|
</template>
|
|||
|
|
</template>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2.2.3 约束管理组件
|
|||
|
|
|
|||
|
|
**文件位置**: `ai-service-admin/src/views/admin/script-flow/components/ConstraintManager.vue`
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<div class="constraint-manager">
|
|||
|
|
<div class="constraint-tags">
|
|||
|
|
<el-tag
|
|||
|
|
v-for="(constraint, index) in modelValue"
|
|||
|
|
:key="index"
|
|||
|
|
closable
|
|||
|
|
@close="removeConstraint(index)"
|
|||
|
|
>
|
|||
|
|
{{ constraint }}
|
|||
|
|
</el-tag>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<el-input
|
|||
|
|
v-model="newConstraint"
|
|||
|
|
placeholder="输入约束条件后按回车添加"
|
|||
|
|
@keyup.enter="addConstraint"
|
|||
|
|
class="constraint-input"
|
|||
|
|
>
|
|||
|
|
<template #append>
|
|||
|
|
<el-button @click="addConstraint">添加</el-button>
|
|||
|
|
</template>
|
|||
|
|
</el-input>
|
|||
|
|
|
|||
|
|
<div class="constraint-presets">
|
|||
|
|
<span class="preset-label">常用约束：</span>
|
|||
|
|
<el-button
|
|||
|
|
v-for="preset in PRESET_CONSTRAINTS"
|
|||
|
|
:key="preset"
|
|||
|
|
size="small"
|
|||
|
|
@click="addPreset(preset)"
|
|||
|
|
>
|
|||
|
|
{{ preset }}
|
|||
|
|
</el-button>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<script setup lang="ts">
|
|||
|
|
const PRESET_CONSTRAINTS = [
|
|||
|
|
'必须礼貌',
|
|||
|
|
'语气自然',
|
|||
|
|
'简洁明了',
|
|||
|
|
'不要生硬',
|
|||
|
|
'不要重复'
|
|||
|
|
]
|
|||
|
|
|
|||
|
|
const addConstraint = () => {
|
|||
|
|
if (newConstraint.value.trim()) {
|
|||
|
|
emit('update:modelValue', [...modelValue.value, newConstraint.value.trim()])
|
|||
|
|
newConstraint.value = ''
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</script>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 数据模型设计
|
|||
|
|
|
|||
|
|
### 3.1 数据库 Schema
|
|||
|
|
|
|||
|
|
**无需修改表结构**，因为 `script_flows.steps` 已经是 JSON 类型。
|
|||
|
|
|
|||
|
|
**现有结构**:
|
|||
|
|
```sql
|
|||
|
|
CREATE TABLE script_flows (
|
|||
|
|
id UUID PRIMARY KEY,
|
|||
|
|
tenant_id VARCHAR NOT NULL,
|
|||
|
|
name VARCHAR NOT NULL,
|
|||
|
|
description TEXT,
|
|||
|
|
steps JSONB NOT NULL, -- 直接扩展此字段
|
|||
|
|
is_enabled BOOLEAN DEFAULT TRUE,
|
|||
|
|
created_at TIMESTAMP DEFAULT NOW(),
|
|||
|
|
updated_at TIMESTAMP DEFAULT NOW()
|
|||
|
|
);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**扩展后的 steps JSON 示例**:
|
|||
|
|
```json
|
|||
|
|
[
|
|||
|
|
{
|
|||
|
|
"step_no": 1,
|
|||
|
|
"script_mode": "flexible",
|
|||
|
|
"intent": "获取用户姓名",
|
|||
|
|
"intent_description": "礼貌询问用户姓名",
|
|||
|
|
"script_constraints": ["必须礼貌", "语气自然"],
|
|||
|
|
"content": "请问怎么称呼您？",
|
|||
|
|
"wait_input": true,
|
|||
|
|
"timeout_seconds": 60
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 向后兼容策略
|
|||
|
|
|
|||
|
|
**读取时**:
|
|||
|
|
```python
|
|||
|
|
def _normalize_step(step: dict) -> dict:
|
|||
|
|
"""确保步骤配置包含所有必需字段"""
|
|||
|
|
return {
|
|||
|
|
"script_mode": step.get("script_mode", "fixed"),
|
|||
|
|
"intent": step.get("intent"),
|
|||
|
|
"intent_description": step.get("intent_description"),
|
|||
|
|
"script_constraints": step.get("script_constraints", []),
|
|||
|
|
"expected_variables": step.get("expected_variables", []),
|
|||
|
|
**step # 保留其他字段
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**写入时**:
|
|||
|
|
- 前端默认 `script_mode = 'fixed'`
|
|||
|
|
- 后端不做强制校验，允许字段缺失
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 技术决策
|
|||
|
|
|
|||
|
|
### 4.1 为什么选择 JSON 扩展而不是新表？
|
|||
|
|
|
|||
|
|
**决策**: 在现有的 `steps` JSON 字段中扩展，而不是创建新表
|
|||
|
|
|
|||
|
|
**理由**:
|
|||
|
|
1. **简化数据模型**: 步骤配置是流程的一部分，不需要独立管理
|
|||
|
|
2. **避免数据迁移**: 无需修改表结构，现有数据自动兼容
|
|||
|
|
3. **灵活性**: JSON 字段易于扩展，未来可以继续添加新字段
|
|||
|
|
4. **性能**: 步骤数量通常不多（<20），JSON 查询性能足够
|
|||
|
|
|
|||
|
|
**权衡**: 无法对意图字段建立索引，但实际场景中不需要按意图查询流程
|
|||
|
|
|
|||
|
|
### 4.2 为什么设置 2 秒超时？
|
|||
|
|
|
|||
|
|
**决策**: LLM 调用超时设置为 2 秒
|
|||
|
|
|
|||
|
|
**理由**:
|
|||
|
|
1. **用户体验**: 对话系统需要快速响应，2 秒是可接受的上限
|
|||
|
|
2. **Fallback 保障**: 超时后立即返回 fallback 话术，不影响流程执行
|
|||
|
|
3. **成本控制**: 避免长时间等待消耗资源
|
|||
|
|
|
|||
|
|
**权衡**: 可能导致部分复杂话术生成失败，但有 fallback 保障
|
|||
|
|
|
|||
|
|
### 4.3 为什么对话历史只取最近 3 轮？
|
|||
|
|
|
|||
|
|
**决策**: 传递给 LLM 的对话历史限制为最近 3 轮
|
|||
|
|
|
|||
|
|
**理由**:
|
|||
|
|
1. **Token 成本**: 减少 Prompt 长度，降低成本
|
|||
|
|
2. **相关性**: 最近 3 轮对话最相关，更早的对话影响较小
|
|||
|
|
3. **性能**: 减少数据库查询和网络传输
|
|||
|
|
|
|||
|
|
**权衡**: 可能丢失更早的上下文信息，但实际影响有限
|
|||
|
|
|
|||
|
|
### 4.4 为什么不缓存生成的话术？
|
|||
|
|
|
|||
|
|
**决策**: 不对生成的话术进行缓存
|
|||
|
|
|
|||
|
|
**理由**:
|
|||
|
|
1. **灵活性优先**: 每次生成都考虑最新的上下文，更符合"灵活话术"的定位
|
|||
|
|
2. **缓存复杂度**: 需要考虑缓存失效策略（上下文变化、配置变化）
|
|||
|
|
3. **实际收益有限**: 同一步骤在同一会话中通常只执行一次
|
|||
|
|
|
|||
|
|
**未来优化**: 如果性能成为瓶颈，可以考虑基于上下文哈希的缓存
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 错误处理与降级策略
|
|||
|
|
|
|||
|
|
### 5.1 话术生成失败
|
|||
|
|
|
|||
|
|
**场景**: LLM 调用超时或返回错误
|
|||
|
|
|
|||
|
|
**处理**:
|
|||
|
|
1. 记录错误日志（包含 tenant_id, session_id, flow_id, step_no）
|
|||
|
|
2. 返回 `step.content` 作为 fallback
|
|||
|
|
3. 在 ChatMessage 中标记 `is_error=False`（因为有 fallback，不算错误）
|
|||
|
|
|
|||
|
|
### 5.2 配置错误
|
|||
|
|
|
|||
|
|
**场景**: flexible 模式但 intent 为空
|
|||
|
|
|
|||
|
|
**处理**:
|
|||
|
|
1. 前端校验：提交时检查必填字段
|
|||
|
|
2. 后端容错：如果 intent 为空，降级为 fixed 模式
|
|||
|
|
|
|||
|
|
### 5.3 模板解析错误
|
|||
|
|
|
|||
|
|
**场景**: 模板语法错误（如 `{unclosed`）
|
|||
|
|
|
|||
|
|
**处理**:
|
|||
|
|
1. 捕获正则匹配异常
|
|||
|
|
2. 返回原始模板（不做替换）
|
|||
|
|
3. 记录警告日志
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 性能考虑
|
|||
|
|
|
|||
|
|
### 6.1 预期性能指标
|
|||
|
|
|
|||
|
|
| 指标 | 目标值 | 说明 |
|
|||
|
|
|------|--------|------|
|
|||
|
|
| 话术生成延迟 (P95) | < 2s | LLM 调用时间 |
|
|||
|
|
| API 响应时间增加 | < 10% | 相比固定模式 |
|
|||
|
|
| 数据库查询增加 | +1 次 | 获取对话历史 |
|
|||
|
|
|
|||
|
|
### 6.2 优化策略
|
|||
|
|
|
|||
|
|
1. **并行查询**: 获取对话历史和流程配置可以并行
|
|||
|
|
2. **限制历史长度**: 只查询最近 3 轮对话
|
|||
|
|
3. **超时控制**: 严格的 2 秒超时，避免长时间等待
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 测试策略
|
|||
|
|
|
|||
|
|
### 7.1 单元测试
|
|||
|
|
|
|||
|
|
**测试文件**: `ai-service/tests/services/flow/test_script_generator.py`
|
|||
|
|
|
|||
|
|
**测试用例**:
|
|||
|
|
- 固定模式：直接返回 content
|
|||
|
|
- 灵活模式：正常生成、超时 fallback、异常 fallback
|
|||
|
|
- 模板模式：变量替换、变量缺失、模板语法错误
|
|||
|
|
|
|||
|
|
### 7.2 集成测试
|
|||
|
|
|
|||
|
|
**测试文件**: `ai-service/tests/api/test_script_flow_intent_driven.py`
|
|||
|
|
|
|||
|
|
**测试场景**:
|
|||
|
|
1. 创建灵活模式流程
|
|||
|
|
2. 启动流程，验证首步话术生成
|
|||
|
|
3. 推进流程，验证后续步骤话术生成
|
|||
|
|
4. 验证对话历史正确传递
|
|||
|
|
|
|||
|
|
### 7.3 端到端测试
|
|||
|
|
|
|||
|
|
**测试场景**:
|
|||
|
|
1. 前端配置灵活模式流程
|
|||
|
|
2. 保存并启用流程
|
|||
|
|
3. 通过 Provider API 触发流程
|
|||
|
|
4. 验证生成的话术符合意图和约束
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 部署与发布
|
|||
|
|
|
|||
|
|
### 8.1 发布顺序
|
|||
|
|
|
|||
|
|
1. **Phase 1**: 后端数据模型和 API 扩展
|
|||
|
|
- 部署后端代码
|
|||
|
|
- 验证 API 向后兼容性
|
|||
|
|
|
|||
|
|
2. **Phase 2**: 后端话术生成引擎
|
|||
|
|
- 部署话术生成逻辑
|
|||
|
|
- 验证 fallback 机制
|
|||
|
|
|
|||
|
|
3. **Phase 3**: 前端配置界面
|
|||
|
|
- 部署前端代码
|
|||
|
|
- 验证配置保存和加载
|
|||
|
|
|
|||
|
|
4. **Phase 4**: 灰度发布
|
|||
|
|
- 选择部分租户启用灵活模式
|
|||
|
|
- 监控性能和错误率
|
|||
|
|
- 全量发布
|
|||
|
|
|
|||
|
|
### 8.2 回滚策略
|
|||
|
|
|
|||
|
|
**如果出现问题**:
|
|||
|
|
1. 前端回滚：恢复旧版本，用户无法配置灵活模式
|
|||
|
|
2. 后端回滚：恢复旧版本，灵活模式降级为固定模式
|
|||
|
|
3. 数据无需回滚：JSON 字段扩展，旧版本可以忽略新字段
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 监控与告警
|
|||
|
|
|
|||
|
|
### 9.1 关键指标
|
|||
|
|
|
|||
|
|
| 指标 | 说明 | 告警阈值 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| script_generation_latency | 话术生成延迟 | P95 > 2.5s |
|
|||
|
|
| script_generation_timeout_rate | 超时率 | > 5% |
|
|||
|
|
| script_generation_error_rate | 错误率 | > 1% |
|
|||
|
|
| fallback_usage_rate | Fallback 使用率 | > 10% |
|
|||
|
|
|
|||
|
|
### 9.2 日志记录
|
|||
|
|
|
|||
|
|
**关键日志**:
|
|||
|
|
```python
|
|||
|
|
logger.info(
|
|||
|
|
f"[AC-IDS-03] Generated script: tenant={tenant_id}, "
|
|||
|
|
f"session={session_id}, flow={flow_id}, step={step_no}, "
|
|||
|
|
f"mode={script_mode}, latency={latency_ms}ms"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
logger.warning(
|
|||
|
|
f"[AC-IDS-05] Script generation timeout, use fallback: "
|
|||
|
|
f"tenant={tenant_id}, session={session_id}, step={step_no}"
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. 未来扩展
|
|||
|
|
|
|||
|
|
### 10.1 短期优化（v1.1）
|
|||
|
|
|
|||
|
|
- 话术生成缓存（基于上下文哈希）
|
|||
|
|
- 更丰富的约束条件预设
|
|||
|
|
- 话术效果评估（用户满意度）
|
|||
|
|
|
|||
|
|
### 10.2 长期规划（v2.0）
|
|||
|
|
|
|||
|
|
- 多轮对话规划（提前生成后续步骤话术）
|
|||
|
|
- 话术 A/B 测试
|
|||
|
|
- 基于历史数据的话术优化建议
|