1. 项目背景与核心目标
这个名为"内智助手"的项目源于一个典型的现代企业痛点：随着公司规模扩张至数百人乃至上千人，各类知识资产分散在Confluence、飞书文档、本地PDF等十多个系统中。技术团队的新人入职后需要花费大量时间寻找文档，法务部门重复审核相似合同条款，而代码审查则依赖个别资深工程师的经验。
我们第一阶段确立了三个核心场景：
- 技术问答：改变传统关键词搜索模式，实现基于语义理解的精准问答
- 代码审查：自动化检查代码规范和安全漏洞
- 合同审查：结合历史案例快速识别风险条款
关键决策：选择这三个场景是因为它们分别代表了知识检索（RAG核心能力）、技术决策（代码规范执行）和业务流程（合同审批）三大企业需求类型，具有足够的代表性和扩展性。
2. 技术架构设计解析
2.1 整体架构拓扑
系统采用分层设计，各层之间通过API网关解耦：
code复制用户层
↓
API网关(鉴权/限流)
↓
Agent协调层
├─ 技术问答Skill → 技术知识库RAG
├─ 代码审查Skill → 代码规范RAG
└─ 合同审查Skill → 合同政策RAG + MCP服务
↓
数据存储层(向量库+业务数据库)
2.2 关键技术选型考量
向量数据库方案对比：
| 方案 | 优点 | 缺点 | 选型理由 |
|---|---|---|---|
| FAISS | 内存计算速度快 | 无持久化能力 | PoC阶段快速验证 |
| Milvus | 支持分布式部署 | 运维复杂度高 | 中期扩展方案 |
| pgvector | 与业务DB天然集成 | 性能中等 | 最终生产环境选择 |
Embedding模型测试数据：
- BGE-M3：在技术文档测试集上达到82%的准确率
- OpenAI text-embedding-3-large：效果最佳但成本高3倍
- 本地化部署的m3e-base：平衡效果与成本
3. 分阶段实施细节
3.1 PoC阶段关键操作
文档预处理流水线：
python复制def process_document(file_path):
# 统一转换为Markdown格式
md_content = convert_to_markdown(file_path)
# 智能分块（保留上下文关系）
chunks = recursive_split(
text=md_content,
chunk_size=600,
overlap=150,
separators=["\n## ", "\n### ", "\n\n"]
)
# 添加元数据
return [{
"text": chunk,
"source": file_path,
"section": extract_section(chunk)
} for chunk in chunks]
评估指标设计：
- 召回率：检索结果是否包含正确答案
- 精确度：返回答案与标准答案的语义相似度
- 人工评分：实际业务人员对回答的满意度
3.2 服务化改造要点
多知识库管理方案：
- 目录结构标准化：
code复制
/data /kb-tech /documents /processed /kb-ops /documents /processed /indexes /kb-tech.faiss /kb-ops.faiss
API设计规范：
python复制@app.post("/rag/query")
async def query(
kb_id: str = Query(..., regex="^kb-[a-z0-9-]+$"),
question: str = Query(..., min_length=3),
top_k: int = Query(5, ge=1, le=10)
):
# 实现细节...
3.3 Skill开发实践
代码审查Skill的工作流：
- 接收代码片段和语言类型
- 从kb-code-style检索相关规范
- 构建包含以下要素的Prompt：
- 代码上下文
- 相关规范条款
- 输出格式要求
- 调用LLM生成结构化报告
合同审查MCP集成：
mermaid复制sequenceDiagram
participant User
participant Agent
participant MCP
participant RAG
User->>Agent: 提交合同ID
Agent->>MCP: get_contract(contract_id)
MCP-->>Agent: 返回合同文本
Agent->>RAG: query(kb-contract-policy, 条款)
RAG-->>Agent: 返回相关条款
Agent->>LLM: 生成审查报告
Agent-->>User: 返回报告
4. 生产环境关键配置
4.1 性能优化方案
缓存策略实现：
python复制class QueryCache:
def __init__(self):
self.cache = TTLCache(maxsize=1000, ttl=3600)
def get_key(self, kb_id: str, question: str) -> str:
return f"{kb_id}:{question.lower().strip()}"
def check_cache(self, key: str) -> Optional[dict]:
return self.cache.get(key)
def set_cache(self, key: str, result: dict):
self.cache[key] = result
负载测试数据：
| 并发数 | 平均响应时间 | 错误率 | 服务器配置 |
|---|---|---|---|
| 50 | 320ms | 0% | 2C4G |
| 100 | 450ms | 0.2% | 2C4G |
| 200 | 1200ms | 5% | 2C4G |
| 200 | 680ms | 0.5% | 4C8G |
4.2 安全控制措施
权限模型设计：
python复制class AccessControl:
ROLES = {
"dev": ["kb-tech", "code-review"],
"legal": ["kb-contract", "contract-review"],
"ops": ["kb-ops"]
}
def check_access(user_role: str, resource: str) -> bool:
return resource in ROLES.get(user_role, [])
敏感信息处理：
python复制def sanitize_input(text: str) -> str:
patterns = [
r"\b\d{4}-\d{4}-\d{4}-\d{4}\b", # 银行卡号
r"\b\d{17}[\dXx]\b", # 身份证号
r"\b1[3-9]\d{9}\b" # 手机号
]
for pattern in patterns:
text = re.sub(pattern, "[REDACTED]", text)
return text
5. 实战经验总结
5.1 文档处理最佳实践
- 分块策略：技术文档采用400-600字符分块，合同文本保持完整条款
- 元数据增强：为每个chunk添加文档来源、章节标题等上下文
- 版本控制：知识库更新采用蓝绿部署模式，确保服务连续性
5.2 效果提升技巧
混合检索方案：
python复制def hybrid_search(query, kb_id):
# 向量检索
vector_results = vector_search(query, kb_id, top_k=3)
# 关键词检索
keyword_results = bm25_search(query, kb_id, top_k=2)
# 结果去重与融合
combined = deduplicate_and_rank(vector_results + keyword_results)
return combined[:5]
Prompt优化模板：
code复制你是一个专业的{角色}，请根据以下上下文回答问题：
相关文档：
{context_str}
问题：{question}
要求：
1. 如果信息不足请明确说明
2. 引用文档中的具体条款
3. 用中文回答，保持专业但易懂
6. 典型问题排查指南
6.1 检索质量下降
排查步骤：
- 检查文档预处理日志是否有异常
- 验证Embedding模型版本是否一致
- 对测试集重新运行评估脚本
- 检查向量索引是否完整加载
常见原因：
- 文档更新后未重建索引
- Embedding模型服务异常
- 分块策略被意外修改
6.2 响应时间波动
优化方法：
- 实施分级缓存：
- 一级缓存：高频问答结果（TTL=1h）
- 二级缓存：向量检索结果（TTL=24h）
- 优化FAISS索引参数：
- nprobe=16 → 8
- 启用量化压缩
- 预加载常用知识库到内存
7. 项目演进路线
7.1 短期优化（1个月内）
- 实现知识库自动同步机制
- 增加用户反馈收集功能
- 完善监控仪表盘
7.2 中期规划（3个月）
- 接入工单系统实现闭环处理
- 开发自定义技能训练界面
- 支持多模态文档处理（图片/表格）
7.3 长期愿景（6个月+）
- 构��企业知识图谱
- 实现跨系统工作流自动化
- 开发移动端语音交互能力
在实际部署中，我们发现最影响用户体验的不是技术精度，而是响应速度和系统稳定性。通过引入本地缓存和异步处理机制，将第95百分位的响应时间从2.1秒降低到890毫秒，用户满意度直接提升了40%。这印证了一个重要原则：在生产环境中，可靠性往往比尖端算法更能创造实际价值。