Pydantic AI Server 推理

配置 Server 相互独立的生成与嵌入模型提供方，并理解其生命周期和失败边界。

这里的 Pydantic AI 运行在 PowerContext Server 内部，负责 schema-bound 生成和独立的嵌入模型提供方。它不会安装 Pydantic AI Agent 适配器，不会给 Agent 增加工具，也不共享 Agent 适配器的生命周期。

状态：本页所用上游 Revision 的 built-in 运行时已提供这项能力。in-process 组合安装 powercontext[builtin]，运行 Server 安装 powercontext[server]；要求 Python 3.11 或更高版本。文档验证没有验证真实模型提供方调用、凭证和生产环境延迟。

​

选择四种运行时状态之一

生成和嵌入都是可选项，彼此独立。无模型 Server 仍有实际用途：显式 Memory 和 FTS 都不依赖模型提供方。

状态	配置	可用能力
无模型	两种模型都不配置	显式 Memory、FTS、类型化提案与 Review，以及类型化 Handoff 操作
仅生成	generation_model	Source 抽取、Experience incubation/生成、Skill 生成、Handoff 生成和可选 Memory 重排序
仅嵌入	完整嵌入配置档	向量/混合 索引 与搜索；显式 Memory 写入仍可用
两者都有	生成加完整嵌入配置档	以上全部能力；两个模型提供方仍各自独立失败

生成不会自动启用调度器。可以手动调用 flush_memory，也可以另行配置 POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS。

​

配置 Server

按运行方式安装其中一个 role。此处固定版本与 LangGraph / LangChain 页相同，写成完整提交哈希：

uv add "powercontext[builtin] @ git+https://github.com/oceanbase/powercontext.git@3e629eb163ba0ddf2935ce3b3fbaced0f9371977"
uv add "powercontext[server] @ git+https://github.com/oceanbase/powercontext.git@3e629eb163ba0ddf2935ce3b3fbaced0f9371977"

Server 设置使用 Pydantic AI 模型字符串。凭证、基础 URL 等模型提供方专用环境变量由所选模型提供方读取。POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL_SETTINGS 接受 JSON 对象，生成流程、重排序和就绪探测会共用这些设置。模型提供方的请求字段应放在 extra_body 下；凭证和静态请求头仍放在模型提供方配置中。只配置非空 settings 而不配置生成模型，或在 settings 中加入 extra_headers，都会导致配置校验失败。

export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL="openai:gpt-5.2"
export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL_SETTINGS='{}'
export POWERCONTEXT_SERVER_INFERENCE_GENERATION_TIMEOUT_SECONDS="30"
export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MAX_REQUESTS="2"

export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL="openai:text-embedding-3-small"
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID="openai-text-embedding-3-small-v1"
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION="1536"
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION="unit"
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS="30"
export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_BATCH_SIZE="10"

uv run powercontext server run

EMBEDDING_MODEL、EMBEDDING_PROFILE_ID、EMBEDDING_DIMENSION 必须全部配置或全部省略。配置不完整时，Server 会在启动前拒绝。Profile 属于持久化向量配置契约；应先确定 ID、维度和规范化，不要在原配置档上随意改动。

模型字符串只是配置，不代表模型提供方已经可用。就绪探测 会发送一次很小的真实请求，但文档验证不保证模型提供方 账户、凭证、配额、区域 端点、模型维度或延迟符合你的部署要求。

​

直接使用 结构化 generator

底层 generator 只接受已经构造并打开的 Pydantic AI Model，传模型字符串会被拒绝。模型生命周期由调用方管理。

from pydantic import BaseModel
from pydantic_ai.models import infer_model

from powercontext.builtin.inference.pydantic_ai import PydanticAIStructuredGenerator


class ExtractionInput(BaseModel):
    text: str


class ExtractionOutput(BaseModel):
    summary: str


async def generate_summary() -> ExtractionOutput:
    async with infer_model("openai:gpt-5.2") as model:
        generator = PydanticAIStructuredGenerator(
            model=model,
            instructions="Return a concise factual summary.",
            input_type=ExtractionInput,
            output_type=ExtractionOutput,
        )
        result = await generator.generate(ExtractionInput(text="The client must be regenerated."))
        return result.output

Server 组合的接口不同：InferenceConfig.generation_model 接受模型字符串，在运行时存活期间打开模型提供方模型，复用于各条生成流程，并随运行时一起关闭。

​

跟踪执行流程

​

生成流程

model string
→ Server opens one provider Model
→ schema-bound PydanticAIStructuredGenerator
→ extraction / incubation / generation / Handoff / optional rerank pipeline
→ domain validation and evidence checks
→ explicit durable write or Candidate Review boundary

Pydantic AI 先校验声明的输出模式，但这只是第一层检查。生成数据进入权威状态前，PowerContext 还会校验领域 规则、证据 reference、当前版本和其他 invariant。生成的 Experience 与 Skill 仍要经过 Candidate Review；结构化 输出不等于批准。

​

嵌入流程

embedding model + profile ID + dimension
→ Server opens the provider and Embedder
→ bounded document batches
→ verify input type, order, count, dimension, normalization, and finite values
→ best-effort write projection or vector/hybrid query

生成和嵌入不会互相后备路径，也没有跨模型提供方后备路径。一个正常时，另一个仍可能降级。

​

理解搜索与写入失败

模型提供方故障只影响依赖它的路径。下表把这些路径与数据库中仍然有效的持久状态分开。

路径	模型提供方失败行为	权威数据
mode="auto" 搜索	查询嵌入暂时失败时，如果 FTS 可用，可以回退到 FTS	不改变持久状态
mode="vector" 或 mode="hybrid" 搜索	返回错误，不会静默改用 FTS	不改变持久状态
write-time 投影嵌入	best effort；投影失败不会丢弃已提交的 Memory	Memory 仍是权威数据，也可由 FTS 找到
generation-backed 操作	超时或不可用会返回给操作	无效或缺失的生成结果不会被当成成功写入

模型提供方超时和 temporary 不可用会映射为 PowerContext 推理错误，并由 Server 返回 HTTP 503。重排嵌入、向量数量或维度错误、非有限值等无效输出会被拒绝，不会写入 索引。

FTS 后备路径成功不能证明向量搜索正常。验证嵌入时，应发起显式向量请求，并要求关联 Source 的命中的 matched_by 包含 vector。

​

准确解读就绪状态

配置生成或嵌入后，会分别增加 non-blocking 就绪状态探测。推理探测失败时是 HTTP 200 的 degraded，不是 not_ready。运行时或数据库失败才是 blocking 失败，会返回 HTTP 503 的 not_ready。

powercontext ready
powercontext capabilities

Server 降级时，不依赖故障模型提供方的 database-backed 操作仍可执行；需要该模型提供方的操作可能返回 503。

就绪探测 只检查当时是否可调用。它不验证生产 配额、流程使用的每一种模式、持续并发、数据质量或完整的 end-to-end 延迟。

​

设定隐私与 Scope 边界

模型提供方会收到操作的序列化输入。根据流程不同，内容可能包括 Source、Memory Candidate、查询、Handoff 证据或 Candidate 生成证据。模型提供方 usage 会记录请求/令牌计数；启用 instrumentation 后还可能发出推理 span。发送敏感项目内容前，应先确认模型提供方的数据处理和 tracing 配置。

Scope 仍只负责选择 PowerContext 数据。它不能阻止已选内容离开 Server 发往配置的模型，不能证明用户身份、授予模型权限或批准生成内容。如果模型提供方不应看到某个敏感信息，就不要把它放进 Source 或 Memory。

​

当前不支持或尚未验证

项目	状态
Pydantic AI Agent 工具或生命周期 Hook	Unsupported；使用独立的 Agent 适配器
generation-to-embedding failover 或跨模型提供方 failover	Unsupported
显式向量/混合搜索静默后备路径	Unsupported
用模式校验代替领域 invariant 或 Review	Unsupported
真实模型提供方凭证、配额、区域 端点和延迟	Not validated；本页未做真实模型提供方验证
生成配置自动启用调度器	Unsupported；需单独配置 scheduling

​

完成检查

依赖推理前，确认：

• 已有意选择四种状态之一；
• 三个必填嵌入字段全部设置或全部省略；
• powercontext ready 能正确区分 ready、degraded 和 not_ready；
• powercontext capabilities 只列出实际配置的搜索与生成能力；
• 显式向量验证失败时错误可见，不会被误认为 FTS 后备路径；
• 模型提供方隐私、tracing、保留策略设置适合各流程发送的数据；
• 模式校验后仍保留下游领域校验与 Candidate Review。

第一次接入请回到 LangGraph 或 LangChain。Pydantic AI Agent 适配器 仍是预览，当前没有可用安装命令，需要时再读。