第10章：上下文工程系统架构设计

如果说前九章是上下文工程的"理论篇"------回答了"什么是上下文"、"如何采集检索记忆压缩"、"在多Agent系统中如何管理上下文"------那么从本章开始，我们进入了"工程篇"。本章聚焦一个核心命题：如何将前面所有章节的理论和策略，落地为一个可运行、可扩展、可观测的企业级上下文引擎。我们将从架构选型开始，逐层拆解上下文引擎的五层参考架构，设计Unix管道式的可组合处理流水线，建立完整的可观测性体系，并讨论高可用与可扩展性的工程策略。

---

10.1 单体架构 vs 微服务架构 vs 云原生架构

上下文引擎的架构选型，是这个系统所有其他设计决策的"第一因"。选错架构，后续的优化都会事倍功半。但"选对"不意味着永远选择最复杂的那一个------选择适合当前阶段和规模的架构，才是真正的工程智慧。

10.1.1 三种架构的核心差异

┌─────────────────────────────────────────────────────┐
│              单体架构 (Monolithic)                    │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │          Context Engine (Single Process)      │   │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐       │   │
│  │  │ 采集  │ │ 存储  │ │ 处理  │ │ 编排  │       │   │
│  │  └──────┘ └──────┘ └──────┘ └──────┘       │   │
│  │  共享内存，直接函数调用，无需网络通信           │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  优势：开发简单、调试方便、部署容易                  │
│  劣势：无法独立扩展某层，故障域是整个进程            │
│  适合：原型验证、小团队、低QPS场景                  │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│              微服务架构 (Microservices)               │
│                                                     │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐          │
│  │ 采集  │  │ 存储  │  │ 处理  │  │ 编排  │          │
│  │ 服务  │  │ 服务  │  │ 服务  │  │ 服务  │          │
│  └──┬───┘  └──┬───┘  └──┬───┘  └──┬───┘          │
│     │         │         │         │                 │
│     └────┬────┴────┬────┴────┬────┘                 │
│          │         │         │                       │
│     ┌────┴─────────┴─────────┴────┐                 │
│     │       消息总线 / API网关     │                 │
│     └─────────────────────────────┘                 │
│                                                     │
│  优势：独立部署、独立扩展、故障隔离                   │
│  劣势：运维复杂、网络延迟、数据一致性挑战             │
│  适合：中型团队、需独立扩展、多团队协作              │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│              云原生架构 (Cloud-Native)                │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │  Serverless Functions (采集触发 / 定时压缩)    │  │
│  └──────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────┐  │
│  │  托管向量数据库 + 托管关系数据库 (无运维)       │  │
│  └──────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────┐  │
│  │  Kubernetes + HPA (水平自动扩缩容)             │  │
│  └──────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────┐  │
│  │  全链路可观测性 (OpenTelemetry + 托管监控)      │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  优势：按需付费、自动扩缩、零运维、高弹性            │
│  劣势：供应商锁定风险、冷启动延迟、成本难预测        │
│  适合：弹性需求、不想管基础设施、快速全球化部署      │
└─────────────────────────────────────────────────────┘

10.1.2 选型决策矩阵

选架构不是选"最好的"，而是选"最合适的"。以下决策框架基于2026年的工程实践：

决策维度	倾向单体	倾向微服务	倾向云原生
团队规模	< 5人	5-20人	不敏感（Serverless屏蔽了运维）
日均请求量	< 1万	1万-100万	不敏感
峰值/均值比	< 3x	3-10x	> 10x（弹性优势明显）
采集源数量	< 5个	5-50个	50+（托管连接器生态优势）
处理链路复杂度	线性管道	分支+并行	事件驱动+动态编排
延迟敏感度	P99 < 200ms	P99 < 500ms	P99 < 1000ms
合规要求	无特殊要求	需要审计追踪	需要区域化部署
成本敏感度	固定预算优先	可预测的成本	弹性成本可接受

10.1.3 2026年的实践建议

从单体开始，但不"停在单体"。 2026年的最佳实践不是"上来就微服务"，而是"模块化单体"------在单体进程中保持模块边界清晰，为未来的拆分做好准备。当某个模块成为瓶颈时（如采集层的Python多线程无法满足QPS需求），再独立拆分部署。

# 模块化单体：清晰的模块边界，为未来微服务化铺路
class ContextEngine:
    """上下文引擎的模块化单体实现
    
    每个模块通过定义良好的接口通信，
    虽然运行在同一个进程中，但边界清晰。
    未来只需将接口改为RPC/消息即可拆分为独立服务。
    """
    
    def __init__(self, config: EngineConfig):
        # 每个模块都是独立的组件，有明确的接口
        self.ingestion = IngestionLayer(config.ingestion)      # 采集层
        self.storage = StorageLayer(config.storage)            # 存储层
        self.processing = ProcessingLayer(config.processing)   # 处理层
        self.orchestration = OrchestrationLayer(config.orchestration)  # 编排层
        self.monitoring = MonitoringLayer(config.monitoring)   # 监控层
    
    async def build_context(self, request: ContextRequest) -> Context:
        """通过管道组装上下文"""
        # 1. 采集：获取多源原始数据
        raw_data = await self.ingestion.fetch(request)
        self.monitoring.record_ingestion(raw_data)
        
        # 2. 存储：按数据特性是写入还是读取
        stored_refs = await self.storage.store_or_retrieve(raw_data, request)
        
        # 3. 处理：过滤、压缩、格式化
        processed = await self.processing.pipeline(stored_refs)
        self.monitoring.record_processing(processed)
        
        # 4. 编排：动态组装最终上下文
        context = await self.orchestration.assemble(processed, request)
        self.monitoring.record_context(context)
        
        return context

---

10.2 2026年企业级上下文引擎参考架构

企业级上下文引擎的参考架构是一个五层模型：采集层、存储层、处理层、编排层和监控层。每一层都是独立的关注域，层与层之间通过定义良好的接口通信。这个五层架构的每一层都可以在本书前面的章节中找到对应的理论和方法论支撑。

10.2.1 上下文采集层：多源数据接入与预处理

采集层是上下文引擎的"感官系统"。它的职责是将来自各种数据源的原始信息统一化为可被后续层消费的标准格式。

职责边界：

采集层的职责不是"加工"，而是"接入和统一"。它解决的是第4章开头提出的第一个问题------"信息从哪来"------但不负责"哪些信息有价值"（那是处理层的职责）。

采集层职责 = 连接多样性 × 格式统一性 × 可靠性
           ≠ 信息筛选（处理层负责）
           ≠ 存储决策（存储层负责）
           ≠ 组装策略（编排层负责）

采集层的核心组件：

from abc import ABC, abstractmethod
from typing import AsyncIterator
import asyncio

class IngestionConnector(ABC):
    """采集连接器的抽象基类------所有数据源接入的统一接口"""
    
    @abstractmethod
    async def connect(self, config: dict) -> bool:
        """建立连接，返回是否连接成功"""
        ...
    
    @abstractmethod
    async def fetch(self, query: dict) -> AsyncIterator[RawDocument]:
        """获取数据，返回异步迭代器（支持大数据量流式处理）"""
        ...
    
    @abstractmethod
    async def health_check(self) -> HealthStatus:
        """健康检查"""
        ...

# 实现示例：数据库连接器
class DatabaseConnector(IngestionConnector):
    async def fetch(self, query: dict) -> AsyncIterator[RawDocument]:
        async with self.pool.acquire() as conn:
            async for row in conn.cursor(query["sql"]):
                yield RawDocument(
                    source=f"database:{query['database']}:{query['table']}",
                    content=json.dumps(dict(row), default=str),
                    metadata={"schema": query["table"], "timestamp": row.get("updated_at")},
                    format="json"
                )

# 实现示例：实时消息流连接器
class KafkaConnector(IngestionConnector):
    async def fetch(self, query: dict) -> AsyncIterator[RawDocument]:
        consumer = await self.create_consumer(query["topic"], query.get("group_id"))
        async for message in consumer:
            yield RawDocument(
                source=f"kafka:{query['topic']}:partition={message.partition}",
                content=message.value.decode("utf-8"),
                metadata={
                    "timestamp": message.timestamp,
                    "offset": message.offset,
                    "partition": message.partition
                },
                format="json" if self._is_json(message.value) else "text"
            )

采集层的设计原则：

1. 每种数据源一个连接器。不要试图用同一个连接器处理文件和API和消息队列。但所有连接器必须实现同一个接口，这样上层代码不需要知道数据来自哪里。
2. 流式优先。如果数据源支持流式获取（Kafka、数据库cursor、文件流），就使用流式------不要等所有数据加载完再处理。这在面对百万级文档时至关重要。
3. 可靠性与重试内建。采集层的网络请求和IO操作都会失败------连接超时、服务重启、分区重分配。每个连接器必须内建指数退避重试和部分失败降级。

10.2.2 上下文存储层：向量数据库、关系数据库、图数据库

存储层的职责是为不同类型的上下文数据选择合适的存储后端。这一层是第4章（元数据工程）、第5章（向量检索）和第6章（层次化记忆）的工程交汇点。

三种存储后端的选择逻辑：

数据特征	最佳存储	典型应用场景
需要语义相似度检索的非结构化文本	向量数据库（Milvus/Qdrant/Pinecone）	文档片段检索、对话历史语义搜索
具有严格Schema的结构化数据	关系数据库（PostgreSQL/MySQL）	用户画像、偏好设置、配置管理
实体关系复杂，需要多跳推理	图数据库（Neo4j/NebulaGraph）	知识图谱、实体关系、因果链

存储层的统一接口设计：

from typing import Protocol, Any, List, Optional

class StorageBackend(Protocol):
    """存储后端的统一协议"""
    
    async def store(self, collection: str, data: dict, 
                    embedding: Optional[List[float]] = None) -> str:
        """存储一条数据，返回存储ID"""
        ...
    
    async def search(self, collection: str, 
                     query: Any, 
                     top_k: int = 10,
                     filters: Optional[dict] = None) -> List[dict]:
        """检索数据"""
        ...
    
    async def delete(self, collection: str, doc_id: str) -> bool:
        """删除数据"""
        ...

# 存储层的路由逻辑
class StorageRouter:
    """根据数据特征自动路由到合适的存储后端"""
    
    def __init__(self):
        self.vector_db = VectorStore(...)
        self.relational_db = RelationalStore(...)
        self.graph_db = GraphStore(...)
        
        # 路由规则：数据特征 → 存储后端
        self.routes = {
            "semantic_text": self.vector_db,     # 需要语义检索的文本
            "structured_profile": self.relational_db,  # 有固定Schema的结构化数据
            "entity_relation": self.graph_db,    # 实体间复杂关系
        }
    
    def route(self, data: dict) -> StorageBackend:
        """根据数据特征自动选择存储后端"""
        if data.get("type") == "user_profile":
            return self.relational_db
        elif data.get("type") == "document_chunk":
            return self.vector_db
        elif data.get("type") == "entity_relation":
            return self.graph_db
        else:
            # 默认：高频检索→向量DB，结构化→关系DB
            if data.get("schema") and data.get("query_pattern") == "exact":
                return self.relational_db
            return self.vector_db

存储层的设计原则：

1. 同一份数据可以在多个后端中存储。一个用户的偏好信息可能同时存储在关系数据库（按用户ID精确查询）和向量数据库（语义检索"哪些用户喜欢Go语言"）中。
2. 存储后端应该对上层透明。编排层只通过统一的StorageRouter访问数据，不需要知道数据被存在哪里。
3. 索引策略是存储层最关键的性能决策。向量索引的类型（HNSW vs IVF vs DiskANN）、标量过滤的索引设计、全文搜索的倒排索引------这些都是需要在数据量和查询模式确定后仔细权衡的地方。

10.2.3 上下文处理层：检索、压缩、过滤、格式化管道

处理层是上下文引擎的"核心加工车间"。它将存储层返回的原始数据转化为可被编排层直接使用的高质量上下文片段。

处理层的定位是第7章（压缩与优化）和第5章（检索）的工程实现。它的核心设计理念是管道化------将每个处理步骤实现为一个独立、可测试、可替换的处理器，然后将它们串联成处理管道。

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import List, Optional

@dataclass
class ContextPiece:
    """管道中流转的上下文片段"""
    content: str
    metadata: dict
    source: str
    tokens: int = 0
    relevance_score: float = 0.0
    quality_flags: List[str] = field(default_factory=list)

class Processor(ABC):
    """处理器的抽象基类"""
    
    @abstractmethod
    async def process(self, pieces: List[ContextPiece], 
                      context: dict) -> List[ContextPiece]:
        """处理一批上下文片段，返回处理后的片段"""
        ...

# 处理器示例1：检索处理器
class RetrievalProcessor(Processor):
    """从存储层检索相关上下文"""
    
    async def process(self, pieces: List[ContextPiece], context: dict) -> List[ContextPiece]:
        query = context["user_query"]
        retrieved = await self.storage.search(
            collection="knowledge_base",
            query=self._build_search_query(query),
            top_k=context.get("retrieval_top_k", 5),
            filters=context.get("retrieval_filters")
        )
        
        return pieces + [
            ContextPiece(
                content=doc["content"],
                metadata={"source": doc["source"], "chunk_id": doc["id"]},
                source="retrieval",
                tokens=self._count_tokens(doc["content"]),
                relevance_score=doc.get("score", 0.0)
            )
            for doc in retrieved
        ]

# 处理器示例2：压缩处理器
class CompressionProcessor(Processor):
    """压缩上下文片段"""
    
    async def process(self, pieces: List[ContextPiece], context: dict) -> List[ContextPiece]:
        budget = context.get("token_budget", 10000)
        current_tokens = sum(p.tokens for p in pieces)
        
        if current_tokens <= budget:
            return pieces  # 不需要压缩
        
        # 按相关性排序，优先保留高相关性片段
        pieces.sort(key=lambda p: p.relevance_score, reverse=True)
        
        compressed = []
        remaining_budget = budget
        
        for piece in pieces:
            if piece.tokens <= remaining_budget:
                compressed.append(piece)
                remaining_budget -= piece.tokens
            elif remaining_budget > 0:
                # 截断最后一个能塞进去的片段
                truncated = self._truncate_to_tokens(piece.content, remaining_budget)
                compressed.append(ContextPiece(
                    content=truncated,
                    metadata={**piece.metadata, "truncated": True},
                    source=piece.source,
                    tokens=remaining_budget,
                    relevance_score=piece.relevance_score
                ))
                break
        
        return compressed

# 处理器示例3：去重处理器
class DeduplicationProcessor(Processor):
    """去除语义重复的上下文片段"""
    
    async def process(self, pieces: List[ContextPiece], context: dict) -> List[ContextPiece]:
        threshold = context.get("dedup_threshold", 0.95)
        unique_pieces = []
        seen_embeddings = []
        
        for piece in pieces:
            embedding = await self.embed(piece.content)
            
            # 检查是否与已存在的片段高度相似
            is_duplicate = any(
                self._cosine_similarity(embedding, seen) > threshold
                for seen in seen_embeddings
            )
            
            if not is_duplicate:
                unique_pieces.append(piece)
                seen_embeddings.append(embedding)
        
        return unique_pieces

处理管道就是这些处理器的有序组合------一个检索处理器负责从存储层拉取相关文档，一个压缩处理器负责将文档裁剪到token预算之内，一个去重处理器负责移除重复或高度相似的内容。这些处理器可以灵活组合------当需求变化时（如需要增加一个新的"格式化处理器"将上下文转化为特定格式），只需实现一个新的Processor类并插入管道即可。

10.2.4 上下文编排层：根据任务动态组装上下文

编排层是上下文引擎的"大脑"。它在前面三层（采集、存储、处理）的基础上，根据当前任务的需求动态决定"需要哪些信息、用哪种策略组装、以什么顺序注入"。

编排层的设计是第3章（六维上下文模型）和第8章（工具调用）的工程高潮------它将分散在不同章节中的策略统一为一个决策引擎。

from enum import Enum
import asyncio

class TaskComplexity(Enum):
    SIMPLE = "simple"        # 单步问答
    MODERATE = "moderate"    # 需要少量检索
    COMPLEX = "complex"      # 多步推理
    MULTI_STEP = "multi_step"  # 长周期Agent任务

class ContextOrchestrator:
    """上下文编排器------根据任务动态组装上下文"""
    
    def __init__(self, config: OrchestratorConfig):
        self.pipeline_registry = {
            # 不同复杂度对应不同的处理管道
            TaskComplexity.SIMPLE: [
                # 简单任务：只加载用户画像和近期短期记忆
                ProfileLoader(),
                ShortTermMemoryLoader(),
                TokenBudgeter(budget=5000),
            ],
            TaskComplexity.COMPLEX: [
                # 复杂任务：除了基本上下文，还需要检索+压缩+去重
                ProfileLoader(),
                ShortTermMemoryLoader(),
                LongTermMemoryLoader(),
                RetrievalProcessor(),
                CompressionProcessor(),
                DeduplicationProcessor(),
                ToolContextLoader(),  # 加载当前任务相关的工具定义
                TokenBudgeter(budget=40000),
            ],
            TaskComplexity.MULTI_STEP: [
                # 长周期任务：在复杂任务基础上增加状态快照和进度追踪
                ProfileLoader(),
                LongTermMemoryLoader(),
                StateSnapshotLoader(),   # 从检查点恢复之前的任务状态
                RetrievalProcessor(),
                CompressionProcessor(),
                TaskProgressTracker(),   # 注入当前任务的进度信息
                ToolContextLoader(),
                TokenBudgeter(budget=80000),
            ],
        }
    
    async def assemble(self, request: ContextRequest) -> AssembledContext:
        """动态组装上下文"""
        # Step 1: 评估任务复杂度
        complexity = await self._assess_complexity(request)
        
        # Step 2: 选择对应的处理管道
        pipeline = self.pipeline_registry[complexity]
        
        # Step 3: 按序执行处理管道
        context_pieces = []
        for processor in pipeline:
            context_pieces = await processor.process(
                context_pieces,
                {"user_query": request.query, "session_id": request.session_id}
            )
        
        # Step 4: 按六维模型组织最终上下文
        assembled = AssembledContext(
            system_instruction=self._build_system_instruction(request, complexity),
            external_knowledge=self._format_knowledge(context_pieces),
            tool_definitions=self._select_relevant_tools(request, complexity),
            persistent_memory=self._build_memory_section(request),
            dynamic_state=self._build_state_section(request),
            user_query=request.query
        )
        
        return assembled

编排层的设计原则：

1. 复杂度驱动的动态管道选择。不是所有任务都需要全量上下文。简单问答（"今天天气怎么样"）和复杂代码重构需要的上下文量级可以差10倍以上。
2. 编排层是策略的执行者，不是策略的发明者。管道中的每个处理器都有自己的清晰职责，编排层只负责"选择哪些处理器、以什么顺序执行"。
3. 按六维模型组织输出。编排层产出的最终上下文应该天然符合第3章定义的六维结构------系统指令层、外部知识层、工具定义层、持久记忆层、动态状态层、用户查询层。

10.2.5 上下文监控层：质量、性能与安全监控

监控层是整个上下文引擎的"神经系统"。它横跨所有其他四层，负责收集指标、追踪异常、触发告警。由于监控层的设计非常复杂且自成体系，我们在10.4节中专门展开。

---

10.3 上下文管道设计：像Unix管道一样组合上下文处理器

Unix管道的哲学是"每个程序做好一件事，通过管道组合完成复杂任务"（Doug McIlroy, 1964）。这个哲学在上下文引擎的设计中同样适用------每个处理器做好一件事（检索、压缩、去重、格式化），通过管道将它们串联成一个完整的上下文处理流水线。

10.3.1 管道设计的四项原则

原则一：每个处理器是单一职责的。 一个"检索+压缩+去重"的三合一处理器难以测试、难以替换、难以理解。分开来，每个处理器只有几十行代码，出问题了容易定位，升级时只替换一个组件。

原则二：处理器之间通过统一的数据结构通信。 所有处理器的输入和输出都是List[ContextPiece]，不引入任何隐式的全局状态。这意味着管道的每个环节可以独立测试------给定一批输入数据，验证输出数据是否符合预期。

# 管道的可测试性示例
async def test_compression_pipeline():
    """独立测试压缩处理器"""
    processor = CompressionProcessor()
    
    # 构造一批模拟的上下文片段
    input_pieces = [
        ContextPiece(content="重要的文档内容..." * 100, tokens=5000, relevance_score=0.9),
        ContextPiece(content="不太重要的内容..." * 50, tokens=2000, relevance_score=0.3),
    ]
    
    # 设置较低的token预算
    result = await processor.process(input_pieces, {"token_budget": 6000})
    
    # 验证：只保留了高相关性的片段，总token不超过预算
    assert len(result) == 1
    assert result[0].relevance_score == 0.9
    assert sum(p.tokens for p in result) <= 6000

原则三：管道是声明式配置的，不是硬编码的。 不同场景对应不同的管道配置------修改管道只需要修改配置，不需要修改代码：

# 声明式管道配置
PIPELINE_CONFIGS = {
    "quick_answer": {
        "processors": [
            {"name": "profile_loader", "params": {"user_fields": ["name", "language"]}},
            {"name": "token_budgeter", "params": {"budget": 5000}},
        ],
        "timeout_ms": 500,
    },
    "code_review": {
        "processors": [
            {"name": "profile_loader", "params": {"user_fields": ["name", "tech_stack"]}},
            {"name": "retrieval", "params": {"top_k": 10, "collections": ["code_docs", "api_docs"]}},
            {"name": "compression", "params": {"strategy": "top_relevance"}},
            {"name": "deduplication", "params": {"threshold": 0.95}},
            {"name": "formatting", "params": {"format": "structured_review"}},
            {"name": "token_budgeter", "params": {"budget": 30000}},
        ],
        "timeout_ms": 3000,
    },
    "long_running_agent": {
        "processors": [
            {"name": "profile_loader", "params": {}},
            {"name": "long_term_memory", "params": {"top_k": 5}},
            {"name": "state_snapshot", "params": {"checkpoint_dir": ".agent/checkpoints"}},
            {"name": "retrieval", "params": {"top_k": 15, "min_score": 0.6}},
            {"name": "compression", "params": {"strategy": "hybrid"}},
            {"name": "deduplication", "params": {"threshold": 0.92}},
            {"name": "tool_context", "params": {"max_tools": 20}},
            {"name": "token_budgeter", "params": {"budget": 80000}},
        ],
        "timeout_ms": 5000,
    },
}

原则四：管道必须可观测。 每个处理器的输入token数、输出token数、处理耗时、丢弃了多少片段------这些指标都必须被采集。没有度量就没有优化。

class InstrumentedProcessor(Processor):
    """带可观测性的处理器装饰器"""
    
    def __init__(self, name: str, processor: Processor, metrics: MetricsCollector):
        self.name = name
        self.processor = processor
        self.metrics = metrics
    
    async def process(self, pieces: List[ContextPiece], context: dict) -> List[ContextPiece]:
        start_time = time.monotonic()
        input_tokens = sum(p.tokens for p in pieces)
        input_count = len(pieces)
        
        try:
            result = await self.processor.process(pieces, context)
            
            output_tokens = sum(p.tokens for p in result)
            output_count = len(result)
            elapsed_ms = (time.monotonic() - start_time) * 1000
            
            # 记录指标
            self.metrics.record_processor_execution(
                processor_name=self.name,
                input_tokens=input_tokens,
                output_tokens=output_tokens,
                input_pieces=input_count,
                output_pieces=output_count,
                elapsed_ms=elapsed_ms,
                compression_ratio=output_tokens / max(input_tokens, 1),
                success=True
            )
            
            return result
        except Exception as e:
            elapsed_ms = (time.monotonic() - start_time) * 1000
            self.metrics.record_processor_execution(
                processor_name=self.name,
                success=False,
                error=str(e),
                elapsed_ms=elapsed_ms
            )
            raise

10.3.2 管道设计的"三个可"

• 可组合性 ：一个处理器的输出可以直接作为下一个处理器的输入。不需要数据转换层，不需要中间格式。List[ContextPiece]是唯一的"管道流体"。
• 可测试性：每个处理器可以独立单元测试。输入构造简单，输出验证简单。管道集成测试只需要验证"给定一个配置，从输入到输出的完整链路是否符合预期"。
• 可观测性：每个处理步骤都有耗时、token变化量、丢弃量的记录。管道整体有总耗时、总token压缩比、各步骤耗时占比。

---

10.4 上下文可观测性体系

可观测性不是"有了就行"，而是"没有就不行"。当一个上下文引擎在生产环境中跑着，你需要知道三件事：它是否正常工作（监控指标）、哪里出了问题（日志与追踪）、如何在你醒来之前发现问题（告警策略）。

10.4.1 核心指标

指标一：缓存命中率------上下文系统性能和成本的头号指标

缓存命中率是上下文工程中最重要的运营指标，没有之一。Manus团队明确表态："缓存命中率是优化Agent成本和延迟的最重要指标。"

# 缓存命中率监控
from prometheus_client import Counter, Gauge

CACHE_HITS = Counter('context_cache_hits_total', 
                      'Total context cache hits', 
                      ['cache_level'])  # semantic | result | embedding
CACHE_MISSES = Counter('context_cache_misses_total',
                        'Total context cache misses',
                        ['cache_level'])
CACHE_HIT_RATIO = Gauge('context_cache_hit_ratio',
                         'Context cache hit ratio',
                         ['cache_level'])

def record_cache_result(cache_level: str, hit: bool):
    if hit:
        CACHE_HITS.labels(cache_level=cache_level).inc()
    else:
        CACHE_MISSES.labels(cache_level=cache_level).inc()
    
    hits = CACHE_HITS.labels(cache_level=cache_level)._value.get()
    misses = CACHE_MISSES.labels(cache_level=cache_level)._value.get()
    total = hits + misses
    if total > 0:
        CACHE_HIT_RATIO.labels(cache_level=cache_level).set(hits / total)

目标阈值：

• 生产环境优良水平：缓存命中率 ≥ 70-80%
• 可接受最低水平：≥ 50%
• 发展方向：优秀团队（如Claude Code）达到90%+

命中率下降时的排查清单：

1. 缓存键生成逻辑是否发生了变化？
2. 是否有新的查询模式导致缓存无法命中？
3. 工具定义（JSON Schema）是否被修改导致KV缓存前缀失效？
4. 是否切换了模型版本？（不同模型的缓存不能共享）
5. 缓存TTL是否过短？是否有大量缓存同时过期？

指标二：Token消耗分布

Tracking token消耗的不是总账（"总共用了多少token"），而是分账（"各个上下文类型分别用了多少token"）：

TOKEN_DISTRIBUTION = Histogram(
    'context_token_count_by_type',
    'Token distribution by context type',
    ['context_type'],  # system_prompt | conversation_history | retrieval_results | tool_results
    buckets=[50, 100, 500, 1000, 2000, 4000, 8000, 16000, 32000]
)

# Token消耗的健康仪表盘
# ┌───────────────────────────────────────────────┐
# │ System Prompt:   ████░░░░░░  8%  (目标 < 10%) │
# │ Conversation:    ████████████ 35% (目标 < 40%) │
# │ Retrieval:       ████████░░  25% (目标 < 35%) │
# │ Tool Results:    ██████░░░░  18% (目标 < 25%) │
# │ Memory:          ██░░░░░░░░  5%  (目标 < 10%) │
# │ ─────────────────────────────────────         │
# │ Total:           18,500 / 64,000 tokens       │
# └───────────────────────────────────────────────┘

指标三：延迟P50/P95/P99

延迟需要分段测量------采集延迟、存储查询延迟、处理管道延迟、编排组装延迟、最终上下文注入延迟。不分段的平均延迟会掩盖真正的瓶颈：

百分位	采集延迟	存储查询	处理管道	编排组装	总计（目标）
P50	< 50ms	< 100ms	< 150ms	< 50ms	< 350ms
P95	< 150ms	< 300ms	< 400ms	< 150ms	< 1000ms
P99	< 300ms	< 500ms	< 800ms	< 300ms	< 2000ms

注：如果涉及远程向量检索，存储查询的P99可放宽至1500ms。

指标四：上下文质量指标

• 信噪比（SNR） = 被LLM实际引用或使用的token数 / 注入上下文的总token数。目标：≥ 0.7。
• 平均检索相关性 = 每个检索文档与查询的余弦相似度均值。目标：≥ 0.82。
• 检索准确率 = 检索结果中实际被LLM引用的比例。目标：≥ 60%。

10.4.2 日志与追踪

结构化日志：上下文变更记录

每次上下文发生结构性的变化------添加了新的检索结果、压缩了旧的对话历史、卸载了工具结果------都应该被记录。这不是为了"调试"（当然也有调试价值），而是为了"理解Agent的决策过程"。

@dataclass
class ContextChangeEvent:
    """上下文变更事件的结构化记录"""
    timestamp: float
    session_id: str
    trace_id: str
    action: str  # "addition" | "removal" | "compression" | "truncation"
    
    # 变更前状态
    before_total_tokens: int
    before_piece_count: int
    
    # 变更后状态
    after_total_tokens: int
    after_piece_count: int
    
    # 变更详情
    affected_pieces: List[str]  # 被影响的片段ID列表
    compression_ratio: float    # 压缩比（仅compression动作）
    reason: str                 # 触发变更的原因

# 示例日志条目
{
    "timestamp": "2026-06-11T10:30:45.123Z",
    "session_id": "session-abc123",
    "trace_id": "trace-xyz789",
    "action": "compression",
    "before_total_tokens": 12500,
    "after_total_tokens": 4200,
    "compression_ratio": 0.336,
    "reason": "context_window_usage > 85% threshold",
    "affected_pieces": ["retrieval-003", "memory-001", "tool-result-007"]
}

分布式追踪：OpenTelemetry集成

2025-2026年，OpenTelemetry的GenAI语义约定已经成为LLM流水线可观测性的事实标准。它定义了标准属性：gen_ai.request.model（模型名称）、gen_ai.usage.input_tokens（输入Token数）、gen_ai.usage.output_tokens（输出Token数）、gen_ai.provider.name（提供商名称）。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# 配置OTEL导出器
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer("context-engine")

span_processor = BatchSpanProcessor(otlp_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

async def build_context_with_tracing(request: ContextRequest):
    """带分布式追踪的上下文构建"""
    with tracer.start_as_current_span("context_engine.build") as span:
        span.set_attribute("session_id", request.session_id)
        span.set_attribute("complexity", request.complexity)
        
        # 每个步骤都是独立的子Span
        with tracer.start_as_current_span("context_engine.retrieval") as retrieval_span:
            docs = await retrieve(request)
            retrieval_span.set_attribute("retrieved_count", len(docs))
            retrieval_span.set_attribute("avg_relevance", avg_score(docs))
        
        with tracer.start_as_current_span("context_engine.processing") as processing_span:
            processed = await process(docs)
            processing_span.set_attribute("input_tokens", count_tokens(docs))
            processing_span.set_attribute("output_tokens", count_tokens(processed))
        
        with tracer.start_as_current_span("context_engine.assembly") as assembly_span:
            context = await assemble(processed)
            assembly_span.set_attribute("total_tokens", context.total_tokens)
            assembly_span.set_attribute("pieces_count", len(context.pieces))
        
        return context

推荐的生产环境配置：全量采样 （OTEL_TRACE_SAMPLING_RATIO=1.0）。对于上下文引擎这类系统，每次执行的追踪对事后分析都有价值------不像传统Web服务可以用统计采样。Langfuse和LangSmith都原生支持OpenTelemetry标准集成。

10.4.3 告警策略

告警策略的根本原则是：只有在需要人类介入时才告警。告警太多，人们会忽略告警；告警太少，问题会被漏掉。

告警一：上下文溢出预警

# Prometheus告警规则：上下文窗口使用率超过80%
alert: ContextWindowNearOverflow
expr: context_current_tokens / context_window_capacity > 0.8
for: 2m
labels:
  severity: warning
annotations:
  summary: "上下文窗口使用率超过80%，将在短时间内触发压缩"

严重级别：使用率超过95% → critical → 强制触发压缩或拒绝新请求。

告警二：缓存命中率骤降

缓存命中率在5分钟滑动窗口内比基线（过去24小时均值）下降超过15% → warning → 触发排查。 持续30分钟未恢复 → critical → 通知值班工程师。

告警三：异常注入检测

分层检测策略（详见第11章）：

1. 第一层：规则匹配，检测常见注入关键词（"ignore previous instructions"等）
2. 第二层：语义异常检测，计算输入与正常行为分布的偏离度
3. 第三层：LLM二次验证

告警触发条件：异常风险分数 > 0.75 → high priority → 同时阻止执行。

告警四：Token预算超支

按日/周追踪token消耗 vs 预算。消耗达到预算的80% → warning → 通知团队控制使用量。超过预算 → critical → 限制非必要功能的token消耗。

告警五：检索质量退化

连续10分钟平均检索相关性分数 < 0.7 或检索命中率从基线下降 > 20% → warning → 排查向量数据库更新、嵌入模型变更、查询分布变化。

10.4.4 监控仪表盘设计

分层仪表盘架构：

• 总览仪表盘（面向运维）：全局缓存命中率趋势、Token消耗日趋势及成本估算、P50/P95/P99延迟曲线、错误率统计。
• 上下文工程仪表盘（面向开发）：Token分布直方图（按类型）、SNR信噪比趋势、检索相关性分布、上下文变更频率统计（平均每会话多少次compression事件）。
• 会话明细追踪（调试用）：单次会话的完整工具调用链可视化、每一步上下文Token变化、质量评分历史、延迟分解（采集/检索/处理/组装各阶段占比）。

---

10.5 高可用与可扩展性设计

上下文引擎在企业级部署中面临两个核心运维挑战：怎么保证它不挂（高可用） 和怎么保证它扛得住（可扩展）。

10.5.1 高可用设计

存储层的高可用：

向量数据库是企业级上下文引擎的核心依赖。2026年的主流方案：

• Qdrant、Milvus：原生支持主从复制和分布式集群部署。生产部署至少3节点。
• Pinecone、Zilliz Cloud：托管服务，SLA通常为99.9%+。
• PostgreSQL + pgvector：适合中小规模，可利用PostgreSQL成熟的流复制和故障转移能力。

# 存储层的故障转移配置
class ResilientStorageRouter:
    def __init__(self):
        self.primary_vector = VectorStore("primary-cluster.milvus.local")
        self.fallback_vector = VectorStore("fallback-cluster.milvus.local")
        self.circuit_breaker = CircuitBreaker(
            failure_threshold=5,
            recovery_timeout=30,  # 30秒后半开
        )
    
    async def search(self, *args, **kwargs):
        try:
            return await self.circuit_breaker.call(
                self.primary_vector.search, *args, **kwargs
            )
        except CircuitBreakerOpen:
            # 主集群不可用，切换到备用集群
            logger.warning("Primary vector store unreachable, falling back")
            return await self.fallback_vector.search(*args, **kwargs)

处理层和编排层的高可用：

处理层和编排层是无状态的------所有状态都存储在存储层。这意味着它们天然支持水平复制：部署多个实例，前面加一个负载均衡器，一个实例挂了流量自动切到其他实例。不需要复杂的分布式共识算法，只需要确保同一个session的请求被路由到同一个实例（会话亲和性）。

10.5.2 可扩展性设计

水平扩展方案：

上下文引擎的瓶颈通常不在CPU（上下文处理是IO密集型的------读数据库、调LLM做压缩摘要），而在并发连接数：

# Kubernetes HPA配置：基于QPS自动扩缩
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: context-engine-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: context-engine
  minReplicas: 3
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Pods
    pods:
      metric:
        name: context_requests_per_second
      target:
        type: AverageValue
        averageValue: "50"  # 每个Pod最多处理50 QPS

存储层的扩展：

• 向量数据库：垂直扩展（更大的内存和更快的磁盘）的收益通常高于水平扩展（分布式索引同步开销较大）。按经验，单节点Qdrant在32GB RAM下可以处理百万级向量。
• 关系数据库：读写分离------写操作走主库，读操作走从库。上下文引擎的读操作远多于写操作。
• 采集层的扩展：采集层最消耗资源的部分是"预处理"（文档解析、文本提取、图像描述生成）。将这些CPU密集型任务卸载到异步任务队列（Celery、Redis Queue），采集主进程只负责接收和分发。

负载均衡策略：

上下文引擎的请求特征与传统Web API不同------有些请求轻量（简单问答，5000 token预算），有些请求重量（代码审查，30000 token预算）。使用最小连接数策略而非轮询策略：

# 使用最小连接数的负载均衡
apiVersion: v1
kind: Service
metadata:
  name: context-engine
spec:
  selector:
    app: context-engine
  ports:
  - port: 80
    targetPort: 8080
  sessionAffinity: ClientIP  # 同一会话的请求路由到同一实例
  sessionAffinityConfig:
    clientIP:
      timeoutSeconds: 3600

故障转移流程：

请求到达
    │
    ├── 主向量数据库健康？
    │       ├── 是 → 正常服务
    │       └── 否 → 切换到备用集群 → 记录故障 → 告警
    │
    ├── 主关系数据库健康？
    │       ├── 是 → 正常服务
    │       └── 否 → 降级：使用本地缓存中的用户画像 → 告警
    │
    └── 降级策略：
            - 向量检索不可用 → 回退到全文搜索（BM25）
            - 用户画像不可用 → 使用默认画像
            - 压缩服务不可用 → 使用简单截断

降级不是"假装一切正常"，而是"告知用户哪些功能当前受限，同时尽可能继续服务"。彻底的不可用（所有存储层都挂了）应该返回明确的错误信息而非崩溃。

---

10.6 实战预告：从零构建上下文引擎

本章讨论的五层参考架构，不仅是纸上谈兵------它将在本书的附录D中转化为一个完整的、可运行的开源参考实现。

附录D将覆盖：

• 一个基于Python/asyncio的完整上下文引擎骨架
• 每个层的核心代码实现（采集连接器、存储路由、处理管道、编排引擎）
• Docker Compose本地开发环境（Qdrant + PostgreSQL + Redis）
• Kubernetes生产部署配置
• Prometheus + Grafana监控仪表盘

附录D的目标是：读完它，你可以在一个周末内搭建起一个最小可行的上下文引擎，并在此基础上进行定制和扩展。

---

本章小结

本章从架构选型到工程落地，系统性地构建了企业级上下文引擎的完整架构蓝图。

10.1节 对比了单体、微服务和云原生三种架构范式，给出了基于团队规模、请求量、复杂度等多维度的选型决策矩阵，并建议"从模块化单体开始，但不停在单体"。

10.2节 系统阐述了2026年企业级上下文引擎的五层参考架构------采集层（多源数据接入的统一接口）、存储层（向量/关系/图数据库的路由选择）、处理层（检索/压缩/去重的可组合管道）、编排层（基于任务复杂度的动态组装引擎）、监控层（横跨所有层的神经系统）。每一层都有明确的职责边界和完整的接口设计。

10.3节 深入了Unix管道式的上下文处理设计------四项原则（单一职责、统一数据结构、声明式配置、嵌入可观测性）和"三个可"（可组合、可测试、可观测），让上下文处理的每个环节都可以独立开发、独立测试、独立优化。

10.4节 建立了完整的上下文可观测性体系------四大核心指标（缓存命中率、Token分布、延迟百分位、质量指标）、结构化日志与OpenTelemetry分布式追踪、五条关键告警策略、以及三层监控仪表盘（运维总览/工程分析/会话明细）。

10.5节 讨论了高可用与可扩展性的工程策略------存储层故障转移、无状态层的水平复制和HPA自动扩缩、基于连接数的负载均衡、以及多级降级策略（向量检索 → 全文搜索 → 默认画像 → 简单截断）。

10.6节 预告了附录D的完整实战------将本章的架构设计转化为可运行的代码实现。

本章是全书的工程架构枢纽------它将第4-9章的所有理论策略整合为一个统一的系统设计。如果说第4章到第9章是每一个战术兵器的详解，本章就是整个战役的作战地图。在下一章，我们将聚焦一个在上下文工程中容易被忽略但至关重要的主题：上下文安全与护栏------如何保护上下文不被攻击、不被滥用、不被泄露。