企业官网建设流程全解析

这类工具最值得先看的不是功能列表，而是能不能在普通环境里稳定跑起来。OpenAI 的 Computer History 和 Record &Replay 功能，这次扩展到了欧洲三个地区，对开发者来说，最直接的价值就是能更方便地测试和调试基于 AI 的交互应用。如果你在做聊天机器人、自动化流程或者需要复现用户操作场景的项目，这个功能能帮你把“用户做了什么”完整录下来，然后精准回放，定位问题。

很多人一听到“历史记录”和“回放”，会觉得这只是个日志功能。但实际上，它解决的是开发和测试里一个很具体的问题：当用户报告“刚才操作出错了”，你怎么知道到底发生了什么？光看日志文本可能不够，你需要看到完整的交互序列——点了哪里、输入了什么、AI 回复了什么、中间状态是什么。Record &Replay 就是干这个的。

适合谁看？主要是三类人：一是正在用 OpenAI API 开发应用的前后端工程师，需要调试复杂的多轮对话；二是做自动化测试的 QA，想用更真实的数据来跑测试用例；三是产品经理或设计师，想复现用户的使用路径来做分析。如果你只是调用简单的文本补全，可能暂时用不上；但一旦你的应用涉及到状态管理、工具调用（Function Calling）或者复杂的流程，这个功能就能省下大量沟通和排查的时间。

我建议先从最小样例开始理解它，别一上来就想处理生产环境的海量数据。下面按实际落地顺序拆一遍。

1. 先搞清楚 Computer History 和 Record & Replay 到底能干什么

很多人容易把这两个功能混为一谈，或者以为只是高级日志。其实它们各有侧重，组合起来才完整。

Computer History的核心是“记录”。它不只是记下用户和 AI 之间一来一往的对话文本，而是记录一个完整的“会话状态”。这包括：

• 消息序列：用户输入、AI 回复、系统指令。
• 工具调用（Function Calling）：AI 在什么时候、以什么参数调用了哪个外部函数，以及函数的返回结果是什么。这是调试复杂工作流的关键。
• 会话元数据：比如会话 ID、创建时间、使用的模型、温度等参数。
• 可能的中间步骤或推理过程（取决于模型和配置）。

你可以把它想象成一个加强版的、结构化的聊天记录。但它不是给你“看”的，主要是给系统“用”的——用于分析、调试，或者作为新会话的上下文。

Record & Replay的核心是“复现”。它允许你基于一段记录下来的 History，完整地重新执行一遍会话。这意味着：

• 你可以用完全相同的输入（用户消息、系统提示、工具定义）去请求 AI。
• 理论上，在模型版本、参数一致的情况下，应该得到相同或高度相似的输出。
• 这对于复现 Bug、进行回归测试、或者对比不同模型/参数的效果，极其有用。

最关键的配合点：当你收到用户反馈说“刚才的对话结果不对”，你可以找到对应的 Computer History，然后用 Record & Replay 功能，在你的开发环境里原样重跑一遍。看看是代码逻辑问题、工具返回数据问题，还是模型本身这次“发挥失常”。这比凭空猜测或者让用户再描述一遍要高效得多。

现在这个功能扩展到欧洲更多地区，意味着如果你在欧洲有服务器或用户，调用这些 API 的延迟可能更低，合规性也更直接。但对于功能本身的使用方法，全球都是一样的。

2. 运行前需要准备什么：环境、权限和关键概念

在动手写代码之前，先确认好环境。这功能不是点开一个网页就能用的，它需要通过 API 来调用。

2.1 账号与 API 密钥

首先，你得有一个 OpenAI 的账号，并且账号要有调用 API 的权限。去 OpenAI 平台创建一个 API Key。记住，这个 Key 要保管好，不要直接写在代码里提交到公开仓库。通常的做法是放在环境变量里。

# 例如在终端中设置（临时） export OPENAI_API_KEY='你的-api-key-here'

2.2 理解核心对象：Threads, Runs, Messages

OpenAI 的 Assistants API（这是使用 Computer History 的主要入口之一）围绕几个核心对象构建，必须理清：

• Assistant：你定义的 AI 助手，包括模型、指令、工具（函数）等配置。
• Thread：一个会话线程。一个 Thread 包含一次用户与 Assistant 的完整对话过程。Computer History 本质上就是对一个 Thread 及其所有 Runs 的完整记录。
• Message：线程中的一条消息，属于用户或助手。
• Run：代表一次“执行”。当你向一个 Thread 添加用户消息后，需要创建一个 Run 来让 Assistant 处理这个消息。Run 会触发模型推理、工具调用等过程。

Record & Replay 通常意味着：创建一个新的 Thread，将历史 Thread 中的 Messages 和状态“灌入”，然后创建一个新的 Run 来重新执行。

2.3 代码环境准备

你需要安装 OpenAI 的官方 Python 库（或其他语言 SDK）。确保版本不要太旧，以支持最新功能。

pip install openai --upgrade

然后，在代码中初始化客户端：

from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # 从环境变量读取 # 如果需要指定特定区域端点，可以在这里设置，但通常不需要 # base_url="https://api.openai.com/v1" )

如果你的应用部署在欧洲，并且你希望数据驻留或获得更低延迟，你可能需要关注 OpenAI 是否为你指定的区域提供了专属端点，并在初始化客户端时配置base_url。不过对于大多数个人开发者和测试场景，用默认的全局端点即可。

3. 实操：如何记录一段 History 并回放它

理论讲完，我们直接看代码。我会用一个简单的例子，模拟一个查询天气的助手。

3.1 第一步：创建助手并运行，生成 History

假设我们有一个能调用“获取天气”工具的助手。

# 1. 创建一个助手 assistant = client.beta.assistants.create( name="天气查询助手", instructions="你是一个天气查询助手。当用户询问天气时，调用 get_current_weather 函数。", model="gpt-4o", # 根据实际情况选择模型 tools=[{ "type": "function", "function": { "name": "get_current_weather", "description": "获取指定城市的当前天气", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "城市名，例如：San Francisco", }, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, }, "required": ["location"], }, }, }] ) # 2. 创建一个线程（这代表一次用户会话） thread = client.beta.threads.create() # 3. 向线程添加用户消息 message = client.beta.threads.messages.create( thread_id=thread.id, role="user", content="北京今天天气怎么样？" ) # 4. 运行助手 run = client.beta.threads.runs.create( thread_id=thread.id, assistant_id=assistant.id ) # 5. 轮询检查运行状态，直到完成或需要动作 while run.status in ['queued', 'in_progress']: run = client.beta.threads.runs.retrieve( thread_id=thread.id, run_id=run.id ) time.sleep(0.5) # 6. 如果运行状态是 `requires_action`，说明模型需要调用工具 if run.status == 'requires_action': tool_calls = run.required_action.submit_tool_outputs.tool_calls tool_outputs = [] for tool_call in tool_calls: if tool_call.function.name == "get_current_weather": # 这里是你的实际业务逻辑，模拟返回数据 weather_data = "晴，25摄氏度，微风。" tool_outputs.append({ "tool_call_id": tool_call.id, "output": weather_data, }) # 提交工具输出结果 run = client.beta.threads.runs.submit_tool_outputs( thread_id=thread.id, run_id=run.id, tool_outputs=tool_outputs ) # 再次轮询直到完成 while run.status in ['queued', 'in_progress']: run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id) time.sleep(0.5) # 7. 运行完成，获取助手的所有回复 if run.status == 'completed': messages = client.beta.threads.messages.list( thread_id=thread.id ) for msg in messages.data: print(f"{msg.role}: {msg.content[0].text.value}")

执行完这段代码，一次完整的交互就完成了。OpenAI 的后台已经为这个thread自动创建了Computer History。它包含了用户消息、模型决定调用工具、你提交的工具输出、以及模型最终生成的回复。这个thread对象及其 ID，就是你进入这份 History 的钥匙。

3.2 第二步：检索并理解保存的 History

如何获取刚才生成的 History？主要是通过 Thread 和 Messages 的 API。

# 检索我们刚刚使用的线程（假设 thread.id 已保存） thread_id = "thread_abc123" retrieved_thread = client.beta.threads.retrieve(thread_id) # 获取这个线程中的所有消息（按时间倒序排列） messages = client.beta.threads.messages.list(thread_id=thread_id, order="asc") # 用 asc 看正序 for msg in messages.data: print(f"--- {msg.role.upper()} ---") print(f"ID: {msg.id}") print(f"Created: {msg.created_at}") # 消息内容 for content in msg.content: if content.type == 'text': print(f"Text: {content.text.value}") # 如果是助手消息，还可能包含工具调用的引用 if hasattr(content.text, 'annotations'): for ann in content.text.annotations: if ann.type == 'file_citation': print(f"Citation: {ann.file_citation.quote}") # 消息的元数据，可能包含关联的 Run ID print(f"Metadata: {msg.metadata}") print()

获取这个线程中的所有执行记录（Runs）

runs = client.beta.threads.runs.list(thread_id=thread_id) for run in runs.data: print(f"Run ID: {run.id}, Status: {run.status}, Model: {run.model}") # 如果 run 调用了工具，可以查看详情 if run.status == 'requires_action' or run.required_action: print(f"Required Action: {run.required_action}") print()

通过以上信息，你可以完整地重建出这次会话的脉络。这就是 **Computer History** 的实质内容。 ### 3.3 第三步：实现 Record & Replay（回放） 回放不是简单的“重新发送同样的问题”。因为模型可能有随机性，简单的重新提问可能得到不同答案。**真正的回放，是尽可能复现完全相同的上下文和状态。** 对于 OpenAI Assistants API，一个直接的“回放”思路是： 1. **创建一个新的、干净的 Thread。** 2. **将历史 Thread 中的所有 Message，按原始顺序和角色，重新添加到这个新 Thread 中。** 这包括了最初的用户消息、以及所有中间的工具调用和输出消息。关键是要确保工具调用的输出和原始历史一致。 3. **使用相同的 Assistant 配置（或者完全相同的 Assistant ID），在新的 Thread 上创建一个 Run。** 4. 理论上，如果模型版本、参数（如温度 temperature 设为 0）完全一致，且工具输出相同，那么这次 Run 的结果应该与历史结果高度一致。 ```python def replay_thread(original_thread_id, assistant_id): """尝试回放一个已有的线程""" # 1. 获取原始线程的历史消息 original_messages = client.beta.threads.messages.list( thread_id=original_thread_id, order="asc" # 按时间正序获取 ) # 2. 创建一个全新的线程 new_thread = client.beta.threads.create() # 3. 将历史消息（除了最后助手生成的最终答案）重新添加到新线程 # 注意：我们通常不需要重现最后一条助手回复，因为我们要重新运行来生成它。 # 我们重现的是导致那条回复的“输入”和“上下文”。 for msg in original_messages.data: # 通常，我们重新添加所有用户消息和工具输出消息。 # 更精细的控制可以检查消息类型和关联的 run。 # 这里简化处理：重新添加所有消息（在实际中，你可能需要过滤或处理工具消息） # 注意：直接复刻消息可能涉及复杂的状态管理，此处仅为概念演示。 # 一个更可行的生产方案是：记录整个 Thread 的步骤（Step）并重现。 pass # 4. 实际上，OpenAI 提供了更直接的“步骤（Steps）”接口来查看运行细节 # 获取原始线程最后一次成功运行的步骤 runs = client.beta.threads.runs.list(thread_id=original_thread_id) last_run_id = runs.data[0].id # 假设取第一个 steps = client.beta.threads.runs.steps.list( thread_id=original_thread_id, run_id=last_run_id ) # 5. 根据 Steps 信息，在新线程中精准重现状态（这是复杂点） # 例如，如果 Step 显示模型调用了工具，那么在新 Run 中，当状态变为 requires_action 时， # 我们必须提交与历史完全相同的工具输出。 # 这需要编写一个状态机来模拟原始运行过程。 # 6. 创建新的运行 new_run = client.beta.threads.runs.create( thread_id=new_thread.id, assistant_id=assistant_id ) # ... 这里需要根据历史 Steps 来拦截和提交工具输出 ... return new_thread.id, new_run.id # 注意：上面的代码是一个概念框架。完全自动化的精准回放需要利用 Runs Steps API 并模拟状态机。 # 对于测试，一个更简单的手动方法是：保存原始对话的“脚本”（用户输入、工具输出），然后写一个测试用例按顺序执行。

重要提示：目前，OpenAI API 没有提供一个单一点的replay(thread_id)方法。Record & Replay 功能更多地体现为一种能力，你需要利用Threads、Messages、Runs和Steps这些 API 组合实现。对于大多数调试场景，查看Steps已经足够定位问题。

3.4 查看运行步骤（Steps）—— 调试利器

StepsAPI 是理解 Computer History 和实现 Replay 的关键。它展示了一个 Run 的详细分解。

# 接前面的代码，获取某个 Run 的步骤 steps = client.beta.threads.runs.steps.list( thread_id=thread.id, run_id=run.id ) for step in steps.data: print(f"Step ID: {step.id}") print(f"Type: {step.type}") # 如：message_creation, tool_calls print(f"Status: {step.status}") # 如：completed, failed print(f"Created: {step.created_at}") if step.step_details.type == 'tool_calls': for tool_call in step.step_details.tool_calls: print(f" Tool Call: {tool_call.type}") print(f" ID: {tool_call.id}") if hasattr(tool_call, 'function'): print(f" Function: {tool_call.function.name}") print(f" Arguments: {tool_call.function.arguments}") print("-" * 20)

通过 Steps，你可以清晰地看到：模型在哪个时间点决定调用工具、调用的具体函数和参数是什么。这比看杂乱的日志清晰多了。当用户报告错误时，你找到对应 Thread 和 Run，查看 Steps，立刻就能知道是模型调用了错误的工具，还是你的工具返回了异常数据。

4. 应用到实际场景：调试、测试与用户支持

知道怎么用 API 之后，我们来看看它能解决哪些实际问题。

4.1 场景一：调试生产环境中的用户会话

问题：用户反馈：“我问助手‘下周末上海天气如何’，它回复了一堆乱码。”传统做法：查看应用日志，可能只有“用户查询天气”、“助手回复成功”这样的记录，看不到模型内部的决策过程和工具返回的具体数据。使用 Computer History：

1. 根据用户 ID 或会话时间，找到对应的thread_id。
2. 调用client.beta.threads.runs.steps.list(thread_id, run_id)。
3. 在 Steps 中，你可能会发现：模型正确调用了get_weather函数，参数是location: “上海”。但是，你的天气服务接口当时返回了一个错误 JSON（比如{“error”: “API limit exceeded”}），这个错误信息被直接作为output提交给了模型。
4. 模型试图解释这个错误 JSON，于是产生了“乱码”回复。结论：问题根源不是 AI 模型，是你的天气服务接口限流了。修复方向是增强后端服务的健壮性和错误处理。

4.2 场景二：自动化回归测试

需求：每次更新助手的指令（instructions）或工具（tools）后，需要确保核心功能（如订餐、查询、计算）仍然正常工作。传统做法：编写模拟用户输入的端到端测试脚本。但测试结果可能因为模型的随机性而波动（温度参数 > 0）。使用 Record & Replay 思路：

1. 为每个核心功能保存一个“黄金会话”（Golden Thread）。这个 Thread 记录了一次成功的、标准的交互流程。
2. 编写测试用例：创建一个新 Thread，按顺序重现黄金会话中的用户消息。
3. 在工具调用环节，不依赖真实外部服务，而是直接注入黄金会话中记录的正确工具输出。
4. 运行测试，将新生成的助手最终回复与黄金会话中的回复进行对比（可以使用文本相似度比较，而不是完全相等）。
5. 将温度（temperature）参数设为 0 或一个很低的值，以减少随机性。好处：测试更稳定，直接针对 AI 决策逻辑，且能快速发现因指令修改导致的意外行为改变。

4.3 场景三：用户支持与工单排查

需求：客服需要理解用户与 AI 助手之间究竟发生了什么误会。做法：在用户管理后台，提供一个“查看会话详情”的功能。当用户提交工单时，关联上其thread_id。实现：后台直接调用Messages和StepsAPI，将整个会话历史（包括隐藏的工具调用）以更友好的方式展示给客服人员。客服能一眼看出是用户描述不清，还是工具返回了错误信息，或是模型误解了意图。这能极大提升解决效率。

5. 边界、限制与避坑指南

功能虽好，但用的时候要知道它的边界在哪里，不然容易踩坑。

5.1 不是所有信息都会被记录

Computer History 主要记录通过 OpenAI API 发生的信息。以下情况需要注意：

• 你本地处理的逻辑：如果用户在和你自己的前端交互时，有些逻辑是在前端或你自有后端处理的，没有通过 Assistants API 的tool_calls和submit_tool_outputs，那么这部分不会出现在 History 中。
• 敏感数据：工具输出中如果包含用户手机号、地址等，这些数据会被记录。你需要考虑数据脱敏和隐私合规问题。OpenAI 提供了数据使用政策，但最终处理责任在你。
• 超大上下文：如果会话非常长，消耗了大量 tokens，History 本身也会很大。检索和存储成本需要考虑。

5.2 Replay 的“确定性”是有限的

即使你完美复现了所有消息和工具输出，以下因素仍可能导致不同结果：

1. 模型更新：OpenAI 会更新模型。今天的gpt-4o和一个月后的gpt-4o在行为上可能有细微差别。
2. 温度（Temperature）等参数：这是最大的变数。如果原始 Run 的温度是 0.7，你回放时也设为 0.7，由于随机性，输出仍可能不同。为了测试，回放时应将温度设为 0。
3. 系统层面的细微差异：API 负载、底层基础设施的微小变化等。

所以，Record & Replay 更适合用于调试和问题复现，而不是作为严格的、追求字节级一致的单元测试。对于测试，应该更关注逻辑正确性（例如，是否调用了正确的工具）而非文本的完全一致。

5.3 成本与数据管理

• API 调用成本：检索 Thread、Messages、Runs、Steps 都需要消耗 API 调用。虽然这些调用可能比完成调用便宜，但如果你频繁为大量会话拉取完整 History，成本会累积。
• 数据保留策略：OpenAI 对数据的保留有自身政策。你不能假设 OpenAI 会永久保存你的 Thread 历史。对于重要的、需要长期审计或分析的会话，你应该定期将 History 数据（通过 API 拉取后）存储到自己的数据库中。
• 导出格式：拉取到的数据是 JSON 结构。你需要设计自己的数据库 schema 来存储threads,messages,runs,steps这些实体及其关系。

5.4 常见错误排查

1. thread_id找不到或无效：检查 ID 是否正确，以及该 Thread 是否属于你的 API Key 所属的组织。Thread 不能跨组织访问。
2. 权限错误：确保你的 API Key 有足够的权限（通常需要assistants:read,assistants:write等）。最新的 API Key 一般都有。
3. 回放时结果差异大：
   • 首先检查温度参数：确保回放 Run 的temperature设置为 0。
   • 检查工具输出：确保你提交的tool_outputs与历史记录中的完全一致（字符串格式、JSON 结构）。
   • 检查助手配置：确保回放使用的assistant_id与创建历史会话的助手是同一个，或者配置（模型、指令、工具列表）完全一致。
4. Steps 信息不完整：Steps只在 Run 完成后的一段时间内保证可用。对于非常旧的 Run，可能无法获取到详细的步骤信息。对于需要长期分析的数据，及时拉取并存储。

6. 个人实践建议与扩展思路

根据我的使用经验，给你几个落地建议：

不要一上来就想着做全自动回放系统。先从最简单的开始：当线上出现一个疑难 Bug 时，手动去 OpenAI 平台或通过脚本，根据thread_id查一下Steps。很多时候，光这一步就能立刻定位问题。把这个流程跑通，让团队感受到价值。

建立 Thread 与你自己业务会话的映射关系。在你的应用数据库里，把你自己的session_id或user_conversation_id和 OpenAI 的thread_id关联起来。这样当用户反馈问题时，你能快速定位到对应的 Thread。

设计你自己的“会话归档”流程。可以定期（比如每天）跑一个脚本，扫描所有已结束的 Thread（可以通过判断最后消息时间是否超过24小时），将其重要的 Messages 和 Steps 数据拉取下来，存储到你的数据仓库或对象存储中。这样既节省了 OpenAI 侧的存储，也便于你进行后续的数据分析和模型优化。

对于测试，采用“脚本化”而非“纯回放”。与其追求 100% 自动化的 API 级回放，不如维护一组核心用户场景的“测试脚本”。这个脚本里写明：

• 用户输入是什么
• 期望模型调用什么工具（或给出什么类型的回复）
• 当模型调用工具时，模拟返回什么数据 这样写出的测试用例更稳定，也更容易理解。

关注欧洲扩展的具体影响。虽然功能全球一样，但扩展到欧洲三地（通常指伦敦、巴黎、法兰克福等地的数据中心）意味着：

• 延迟降低：欧洲用户的请求可能路由到更近的服务器，响应更快。
• 数据驻留：可能满足某些欧洲数据必须存储在欧盟境内的合规要求（需确认 OpenAI 的具体条款）。
• 计费单元：价格可能因区域略有差异，调用前确认清楚。 如果你的主要用户在欧洲，可以在初始化客户端时尝试指定区域端点（如果 OpenAI 提供），并测试性能提升。

最后，记住这个功能的本质是“增强可观测性”。它把 AI 交互这个黑盒打开了一个窗口，让你能看到模型决策的中间过程。用好它，能显著提升你开发、调试和运营 AI 应用的能力。先从解决一个具体的调试痛点开始，再逐步扩展到测试和数据分析，这样迭代最稳妥。