Java 17调用gpt-transcribe实现会议录音转写与术语提示

会议转写最让人头疼的往往不是普通话，而是“AC-42”“Responses API”这类业务词。模型可能把它们写成发音相近的普通词，后续搜索和纪要就一起失效。这个教程用Java 17上传一段已录完的音频，调用gpt-transcribe，再用上下文、关键词和语言提示改善专有名词识别。你还会学会在上传前检查格式与大小，并把“提示词可能诱导幻听”纳入验收。

先选对接口：文件转写还是实时转写

ASR（Automatic Speech Recognition，自动语音识别）有两类常见输入。录音已经结束、需要最终全文时，使用文件转写；麦克风或电话音频仍在持续到达时，使用Realtime实时转写。不要为了“看起来实时”把完整会议切成大量小文件并并发上传，这会破坏上下文，还可能让专有名词在每段开头反复丢失。

OpenAI官方文件转写文档当前推荐普通录音从gpt-transcribe开始。单文件上限25MB，支持mp3、mp4、mpeg、mpga、m4a、wav和webm。需要说话人标签、逐词时间戳、字幕或翻译时，再选择相应的专用模型与响应格式。

技术原理

prompt提供录音背景，例如“客户讨论高级套餐和账号”；keywords提供可能出现的字面术语；languages缩小候选语言范围。它们都是提示，不是强制答案。关键词放得太多或包含未说出的品牌名，反而可能让模型把噪声“听成”提示词。因此术语表应短、与会议主题相关，并通过有标准答案的录音评测。

环境准备

需要Java 17+、Maven和有效密钥。Maven依赖：

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.75.1</version>
</dependency>

export OPENAI_API_KEY="你的密钥"
export OPENAI_EXAMPLE_AUDIO_PATH="meeting.wav"
mvn -q compile exec:java -Dexec.mainClass=MeetingTranscriber

完整代码

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.audio.transcriptions.TranscriptionCreateParams;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.List;
import java.util.Set;

public class MeetingTranscriber {
  private static final long MAX_BYTES = 25L * 1024 * 1024;
  private static final Set<String> EXTENSIONS = Set.of(
      "mp3", "mp4", "mpeg", "mpga", "m4a", "wav", "webm");

  public static void main(String[] args) {
    String key = System.getenv("OPENAI_API_KEY");
    String audioEnv = System.getenv("OPENAI_EXAMPLE_AUDIO_PATH");
    if (key == null || key.isBlank() || audioEnv == null || audioEnv.isBlank()) {
      System.err.println("请设置 OPENAI_API_KEY 和 OPENAI_EXAMPLE_AUDIO_PATH");
      System.exit(2);
    }

    Path audio = Path.of(audioEnv);
    try {
      if (!Files.isRegularFile(audio)) {
        throw new IllegalArgumentException("音频文件不存在: " + audio);
      }
      String name = audio.getFileName().toString().toLowerCase();
      String ext = name.contains(".") ? name.substring(name.lastIndexOf('.') + 1) : "";
      if (!EXTENSIONS.contains(ext)) {
        throw new IllegalArgumentException("不支持的格式: " + ext);
      }
      if (Files.size(audio) > MAX_BYTES) {
        throw new IllegalArgumentException("文件超过25MB，请先压缩或合理分段");
      }

      OpenAIClient client = OpenAIOkHttpClient.builder()
          .fromEnv()
          .timeout(Duration.ofSeconds(90))
          .build();

      TranscriptionCreateParams params = TranscriptionCreateParams.builder()
          .file(audio)
          .model("gpt-transcribe")
          .prompt("一场中文产品会议，讨论Responses API、AC-42账号和billing账单。")
          .putAdditionalBodyProperty(
              "keywords",
              JsonValue.from(List.of("Responses API", "AC-42", "billing")))
          .putAdditionalBodyProperty(
              "languages", JsonValue.from(List.of("zh", "en")))
          .build();

      var result = client.audio().transcriptions().create(params);
      String text = result.asTranscription().text();
      if (text == null || text.isBlank()) {
        throw new IllegalStateException("API返回空转写，请人工检查音频");
      }
      System.out.println(text);
    } catch (Exception ex) {
      System.err.println("转写失败: " + ex.getMessage());
      System.exit(1);
    }
  }
}

逐段解释

代码先验证两个环境变量，避免把密钥写进源码或把空路径交给SDK。随后检查文件是否存在、扩展名是否受支持以及是否超过25MB。扩展名检查只能防明显误用，不能证明文件内容真实；生产系统还应读取媒体头、限制时长，并在隔离环境中做恶意文件扫描。

客户端超时设为90秒，因为上传和转写音频通常比文本请求慢。参数中的prompt描述上下文，keywords只列三项真正可能出现的术语，languages表示中英混合。官方特别提醒：gpt-transcribe使用复数languages，不要再同时发送旧的单数language字段。

最后读取转写文本并拒绝空结果。示例没有自动生成会议结论，因为“听清楚”与“总结正确”是两个评测问题。更稳妥的做法是先保存可追溯转写，再由另一个结构化步骤抽取行动项，并把时间、说话人或原始音频片段作为证据。