# openai.BadRequestError：response_format 的架构无效：'properties' 必须是一个对象

- **ID:** `llm/structured-output-schema-mismatch-on-retry`
- **领域:** llm
- **类别:** config_error
- **错误码:** `invalid_response_format`
- **验证级别:** ai_generated
- **修复率:** 88%

## 根因

OpenAI API 对 response_format 强制执行严格的 JSON Schema 验证；空的或格式错误的 'properties' 字段（例如在架构转换或缓存后）会在重试时触发此错误。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| openai==1.30.0 | active | — | — |
| openai==1.35.0 | active | — | — |
| pydantic==2.7.0 | active | — | — |

## 解决方案

1. ```
   Validate the schema before sending: ensure 'properties' is a non-empty object with valid JSON Schema types. Example: `if not isinstance(schema.get('properties'), dict) or len(schema['properties']) == 0: raise ValueError('Invalid schema')`
   ```
2. ```
   Use a schema generation library like Pydantic to create the JSON Schema, then convert to dict with `model_json_schema()`. Example: `from pydantic import BaseModel; class MyModel(BaseModel): name: str; schema = MyModel.model_json_schema()`
   ```
3. ```
   If caching schemas, deep-copy the schema dict before modification to avoid mutating the cached version (which may become empty). Example: `import copy; schema = copy.deepcopy(cached_schema)`
   ```

## 无效尝试

- **** — The schema is fundamentally broken; the API will reject it consistently until the schema is corrected. (95% 失败率)
- **** — Removing structured output forces the LLM to return free-form text, breaking downstream parsing logic that expects a JSON object. (85% 失败率)
- **** — The API expects the schema directly under 'response_format', not nested; this causes a different validation error. (90% 失败率)