本文详解 OpenAI Assistants API 中 vector store 文件上传后显示空或长期处于 in_progress 状态的根本原因，聚焦 JSON 文件格式合规性这一高频隐蔽陷阱，并提供可验证的修复代码、调试方法及生产级最佳实践。
本文详解 openai assistants api 中 vector store 文件上传后显示空或长期处于 in_progress 状态的根本原因，聚焦 json 文件格式合规性这一高频隐蔽陷阱，并提供可验证的修复代码、调试方法及生产级最佳实践。
在使用 OpenAI Assistants API 构建知识增强型智能体时，向 vector store 上传结构化数据（如 JSON）是常见需求。但许多开发者会遇到两种典型失败现象：
-
方式一（直接上传）：调用
upload_and_poll后vector_store.file_counts.total == 0，无报错却“静默失败”； -
方式二（先创建 file 再关联）：
vector_store.file_counts.in_progress == N持续不归零，文件始终卡在处理中。
⚠️ 关键真相：OpenAI 的文件处理器对 JSON 格式有严格语法校验，且仅接受标准 JSON（RFC 8259），不兼容 JavaScript 风格的非引号键名（如 {key: "value"}）。这正是 Web UI 可成功而 API 调用失败的核心原因——UI 通常自动格式化/容错，而 API 层则零容忍。
✅ 正确 JSON 格式示例（必须满足）
{
"title": "Sample Document",
"content": "This is valid JSON.",
"metadata": {
"source": "tsm_human_labeled.json",
"version": 1
}
}
❌ 错误示例（导致 in_progress 卡死）：
{
title: "Sample Document", // ❌ 键名未加双引号
content: "Invalid JSON", // ❌ 同上
metadata: { // ❌ 嵌套对象键名也需引号
source: "tsm_human_labeled.json"
}
}
? 修复步骤（三步落地）
1. 自动化 JSON 格式校验与修复
使用 Python 内置 json 模块预检并标准化：
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
import json
def validate_and_fix_json(file_path: str) -> str:
"""读取并重写 JSON 文件，确保符合 RFC 8259 标准"""
try:
with open(file_path, "r", encoding="utf-8") as f:
data = json.load(f) # 自动校验语法
# 重新序列化为规范格式（强制双引号、无尾逗号、UTF-8）
fixed_path = file_path.replace(".json", "_fixed.json")
with open(fixed_path, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
print(f"✅ 已生成规范 JSON: {fixed_path}")
return fixed_path
except json.JSONDecodeError as e:
raise ValueError(f"JSON 解析失败，请检查语法: {e}")
# 使用示例
fixed_json1 = validate_and_fix_json("results/results_tsm_human_labeled.json")
fixed_json2 = validate_and_fix_json("data/sample_tsm_new.json")
2. 采用推荐上传方式（带显式错误捕获）
优先使用 upload_and_poll（避免 file_ids 关联的异步不确定性），并添加状态轮询日志：
from openai import OpenAI
import time
client = OpenAI()
vector_store = client.beta.vector_stores.create(
name="human labeled dataset",
)
for file_path, chunk_config in [
(fixed_json1, {"max_chunk_size_tokens": 100, "chunk_overlap_tokens": 5}),
(fixed_json2, {"max_chunk_size_tokens": 1000, "chunk_overlap_tokens": 400}),
]:
print(f"? 开始上传 {file_path}...")
try:
upload_resp = client.beta.vector_stores.files.upload_and_poll(
vector_store_id=vector_store.id,
file=open(file_path, "rb"),
chunking_strategy={
"type": "static",
"static": chunk_config,
},
poll_interval_ms=2000,
)
print(f"✅ 上传完成，文件 ID: {upload_resp.id}")
except Exception as e:
print(f"❌ 上传失败: {e}")
raise
# 主动检查最终状态
final_vs = client.beta.vector_stores.retrieve(vector_store.id)
print(f"? Vector Store 状态: {final_vs.file_counts}")
# 输出应为: total=2, in_progress=0, completed=2, failed=0
3. 生产环境加固建议
-
前置校验流水线：CI/CD 中集成
jq -n 'true' 或 Python 脚本，拒绝非标准 JSON 提交； -
监控告警：对
vector_store.file_counts.in_progress > 0持续超 5 分钟的实例触发告警； -
降级策略：若多次上传失败，自动切换至 Web UI 手动上传 +
file_id回填（适用于紧急发布）； -
版本注意：截至 2026 年 8 月，此行为在
assistantsv2（/v1/assistants）和迁移后的responsesAPI（/v1/responses）中均保持一致，不是已知 Bug，而是设计约束。
? 延伸提示：除 JSON 外，CSV、TXT 等格式也需注意编码（必须 UTF-8）与换行符（LF
\n，非 CRLF\r\n）。若仍失败，可通过client.beta.vector_stores.files.list(vector_store_id=vs.id)查看具体文件的status字段（如"error"会附带last_error详情）。
通过强制统一 JSON 格式标准，90% 以上的 in_progress 卡死与空 vector store 问题将被根治。记住：API 是精密仪器，UI 是友好向导——生产环境永远以 API 的严苛要求为准绳。
