Back to Details

pydantic-ai

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PydanticAI

PydanticAI

When to use this skill

何时使用此技能

  • LLM 출력이 JSON/객체 스키마를 반드시 따라야 할 때
  • 후속 자동화(저장/분석/API 호출)에 안정적으로 넘겨야 할 때
  • 자유서술보다 검증 가능한 구조화 출력이 중요한 경우
  • 当LLM输出必须遵循JSON/对象架构时
  • 需要稳定交付给后续自动化流程（存储/分析/API调用）时
  • 可验证的结构化输出比自由文本更重要的情况

Instructions

使用说明

Step 1) 스키마 우선 설계

步骤1）架构优先设计

  • 먼저 Pydantic 모델을 정의하고 필수/선택 필드 분리
  • enum/range/regex 제약을 명시
  • 오류 메시지는 사용자 교정 가능 형태로 설계
  • 首先定义Pydantic模型，区分必填/可选字段
  • 明确enum/range/regex约束
  • 错误消息设计为用户可修正的形式

Step 2) Agent + Tool 결합

步骤2）Agent与工具结合

  • 도구 입출력도 Pydantic 타입으로 통일
  • 실패 시 재시도 규칙(필드 누락/타입 불일치)을 분리
  • 모델 출력이 스키마 미준수면 즉시 재질문(repair prompt)
  • 工具的输入输出也统一为Pydantic类型
  • 分离失败时的重试规则（字段缺失/类型不匹配）
  • 若模型输出不符合架构，立即发起修复提示（repair prompt）

Step 3) 검증/복구 루프

步骤3）验证/修复循环

  • ValidationError를 카테고리화(누락/형식/논리)
  • 동일 오류 반복 시 프롬프트가 아니라 스키마 복잡도 재검토
  • 최종 결과에 신뢰 플래그(validated, repaired, failed) 포함
  • 将ValidationError分类（缺失/格式/逻辑）
  • 当同一错误重复出现时，重新审视架构复杂度而非提示词
  • 在最终结果中包含可信度标记（validated, repaired, failed）

Step 4) 운영 적용

步骤4）生产环境部署

  • DB 저장 전 2차 검증(서버 측) 수행
  • 버전드 스키마(
    v1
    ,
    v2
    )로 호환성 관리
  • 관찰 지표: first-pass success, retry rate, field error rate
  • 存储到数据库前执行二次验证（服务器端）
  • 使用版本化架构（
    v1
    、
    v2
    ）管理兼容性
  • 观测指标：first-pass success, retry rate, field error rate

Examples

示例

  • 요청: "리서치 결과를 항상 동일 포맷 JSON으로 받아서 파이프라인에 넣고 싶다"
  • 적용: 
    ResearchSummary
    스키마 정의 후 Agent 결과를 강제 검증
  • 결과: 파싱 실패율 감소, 후속 자동화 안정화
  • 请求：“希望始终以相同格式的JSON接收研究结果并接入流水线”
  • 应用：定义
    ResearchSummary
    架构后强制验证Agent的结果
  • 结果：解析失败率降低，后续自动化流程更稳定

Best practices

最佳实践

  1. 자연어 요구사항을 먼저 스키마로 번역한다.
  2. 스키마는 작게 시작하고 점진적으로 확장한다.
  3. 재시도 횟수보다 오류 분류 품질을 먼저 개선한다.
  1. 先将自然语言需求转换为架构。
  2. 从简单的架构开始，逐步扩展。
  3. 优先提升错误分类质量，而非增加重试次数。

References

参考资料