generative-ai-for-beginners 第 8 课用转录数据预处理脚本构建语义搜索视频索引流水线【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本篇技术指南聚焦于 generative-ai-for-beginners 仓库第 8 课「构建搜索应用」中的转录数据预处理Transcription Data Prep脚本族它们负责从 YouTube 播放列表批量下载视频转录文本再依次完成说话人识别、分段时间桶切分、LLM 摘要与 Embedding 向量化最终产出可供语义搜索应用直接加载的索引文件。读完本文你将掌握这套脚本的完整运行链路、Azure OpenAI 资源的最小化配置方式以及每个脚本在数据流水线中的源码级职责与关键参数。一、脚本在项目中的定位在 08-building-search-applications 一课中课程演示了如何基于 OpenAI Embeddings 构建语义搜索应用。语义搜索的前提是拥有一份已经向量化的语料索引——而本套脚本正是这份索引的生产者它把「一段 YouTube 播放列表」加工成「一份带 Embedding 的 JSON 索引」供课程中的 oai-solution.ipynb 与 aoai-solution.ipynb 查询使用。全部脚本位于 08-building-search-applications/scripts 目录并已在 Windows 11、macOS Ventura 与 Ubuntu 22.04及以上版本上完成验证。目录内包含 6 个 Python 脚本、3 个平台启动脚本.sh/.ps1/.bat、依赖清单 requirements.txt 以及一份可直接查看的产出样例 embedding_index_3m.json。二、流水线总体流程六步加工从 prepare_transcripts_ai_show.sh 的注释可以完整还原整条流水线从 YouTube 播放列表下载转录文本transcript_download.py为每段视频补充说话人信息transcript_enrich_speaker.py将转录切分为按分钟计的时间桶transcript_enrich_bucket.py使用 LLM 为每个时间桶生成摘要transcript_enrich_summaries.py为文本生成 Embedding 向量transcript_enrich_embeddings.py生成轻量索引——移除text字段以缩减体积transcript_enrich_lite.py。每个脚本独立、可单独执行且通过-f转录文件夹参数串联协作最终把中间产物收敛到folder/output/目录下。三、创建 Azure OpenAI 服务资源脚本依赖 Azure OpenAI 提供摘要与 Embedding 能力官方文档推荐先把 Azure CLI 升级到最新版本以保证与 OpenAI 的兼容性。3.1 创建资源组以下指令默认使用资源组semantic-video-search、区域eastusaz group create --name semantic-video-search --location eastus若更换资源位置务必先核对模型可用性表确认所选区域已上线需要的模型。3.2 创建 Azure OpenAI 服务实例az cognitiveservices account create --name semantic-video-openai --resource-group semantic-video-search \ --location eastus --kind OpenAI --sku s03.3 获取 Endpoint 与密钥az cognitiveservices account show --name semantic-video-openai \ --resource-group semantic-video-search | jq -r .properties.endpoint az cognitiveservices account keys list --name semantic-video-openai \ --resource-group semantic-video-search | jq -r .key13.4 部署两个模型需要部署两个模型部署Deploymenttext-embedding-ada-002版本2或更高部署名text-embedding-ada-002——用于向量化gpt-5-mini部署名gpt-5-mini——用于说话人提取与摘要生成。az cognitiveservices account deployment create \ --name semantic-video-openai \ --resource-group semantic-video-search \ --deployment-name text-embedding-ada-002 \ --model-name text-embedding-ada-002 \ --model-version 2 \ --model-format OpenAI \ --scale-settings-scale-type Standard az cognitiveservices account deployment create \ --name semantic-video-openai \ --resource-group semantic-video-search \ --deployment-name gpt-5-mini \ --model-name gpt-5-mini \ --model-format OpenAI \ --sku-capacity 100 \ --sku-name Standard需要注意transcript_enrich_summaries.py与transcript_enrich_speaker.py默认读取AZURE_OPENAI_MODEL_DEPLOYMENT_NAME环境变量缺省值即gpt-5-minitranscript_enrich_embeddings.py默认读取AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT缺省值为text-embedding-ada-002。部署名必须与环境变量保持一致。四、运行环境Python 版本、环境变量与依赖安装4.1 软件要求Python 3.9 或更高版本。4.2 环境变量运行转录预处理脚本需要四个环境变量AZURE_OPENAI_API_KEY your Azure OpenAI Service API key AZURE_OPENAI_ENDPOINT your Azure OpenAI Service endpoint AZURE_OPENAI_MODEL_DEPLOYMENT_NAME your Azure OpenAI Service model deployment name GOOGLE_DEVELOPER_API_KEY your Google developer API keyWindows推荐通过「系统属性 → 环境变量 → 用户变量」界面添加Linux / macOS推荐把导出语句追加到~/.bashrc或~/.zshrcexport AZURE_OPENAI_API_KEYyour Azure OpenAI Service API key export AZURE_OPENAI_ENDPOINTyour Azure OpenAI Service endpoint export AZURE_OPENAI_MODEL_DEPLOYMENT_NAMEyour Azure OpenAI Service model deployment name export GOOGLE_DEVELOPER_API_KEYyour Google developer API key其中GOOGLE_DEVELOPER_API_KEY仅供transcript_download.py通过 YouTube Data API v3 枚举播放列表使用AZURE_OPENAI_*三个变量则被后续四个 enrich 脚本通过os.environ直接读取见各脚本头部如 transcript_enrich_speaker.py。4.3 安装 Python 依赖requirements.txt 锁定了关键依赖及其版本区间openai1.54.0,2.0.0新版 OpenAI SDK脚本统一使用client.responses.create与client.embeddings.creategoogle-api-python-client、youtube-transcript-apiYouTube 播放列表枚举与转录下载tiktoken本地 token 计数bpe 编码用于控制分桶长度tenacity带随机指数退避的重试机制处理限流rich并发任务的进度条展示pandas、matplotlib、plotly、scipy、scikit-learn供下游搜索示例做向量检索与可视化本套脚本自身不直接使用。安装步骤先确保已安装 git 客户端git clone https://github.com/gloveboxes/semanic-search-openai-embeddings-functions.git cd semanic-search-openai-embeddings-functions/src/data_prep在项目根目录下创建并激活虚拟环境然后安装依赖python3 -m venv .venv source .venv/bin/activate pip3 install -r requirements.txtWindows 下对应为python -m venv .venv、.venv\Scripts\activate、pip install -r requirements.txt。五、一键运行三平台启动脚本启动脚本把六个 Python 脚本串成一条命令链并处理输出文件命名。以 prepare_transcripts_ai_show.sh 为例其核心逻辑为export TRANSCRIPT_FOLDERtranscripts_the_ai_show export TRANSCRIPT_BUCKET_MINUTES3 mkdir -p $TRANSCRIPT_FOLDER/output python3 transcript_download.py -f $TRANSCRIPT_FOLDER -p PLlrxD0HtieHi0mwteKBOfEeOYf0LJU4O1 python3 transcript_enrich_speaker.py -f $TRANSCRIPT_FOLDER python3 transcript_enrich_bucket.py -f $TRANSCRIPT_FOLDER -m $TRANSCRIPT_BUCKET_MINUTES python3 transcript_enrich_summaries.py -f $TRANSCRIPT_FOLDER python3 transcript_enrich_embeddings.py -f $TRANSCRIPT_FOLDER python3 transcript_enrich_lite.py -f $TRANSCRIPT_FOLDER执行入口Windows.\transcripts_prepare.ps1macOS / Linux./transcripts_prepare.sh启动脚本末尾会把中间产物改名并保留分桶时长信息master_enriched.json改名为embedding_index_full_3m.json完整版master_enriched_lite.json改名为embedding_index_3m.json轻量版。仓库中 embedding_index_3m.json 正是该流水线产出的样例可直接用于搜索应用调试。六、源码级解析六个脚本的职责与关键实现6.1 转录下载transcript_download.pytranscript_download.py 负责「下载」环节主要机制通过googleapiclient.discovery.build创建 YouTube Data API v3 客户端以playlistItems().list(partsnippet, playlistId..., maxResults50)分页拉取播放列表条目借助nextPageToken翻页直到拉完见 transcript_download.py对每个视频调用YouTubeTranscriptApi.get_transcript(video_id)获取转录并以 JSON 形式保存为videoId.json.vtt同时把标题、描述、videoId 等元数据写入videoId.json见 transcript_download.py采用 40 个线程并发消费队列以加速批量下载PROCESSING_THREADS 40命令行参数-f/--folder指定输出文件夹-p/--playlist指定播放列表 ID二者必填缺失即退出。6.2 说话人提取transcript_enrich_speaker.pytranscript_enrich_speaker.py 使用 OpenAI Functions工具调用从标题、描述与转录前 3 分钟文本中提取说话人姓名定义工具get_speaker_name要求模型返回逗号分隔的说话人名单见 transcript_enrich_speaker.py系统提示要求「从标题中提取说话人姓名姓名通常少于 3 个词」通过client.responses.create(..., toolsopenai_functions, tool_choice{type: function, name: get_speaker_name})强制模型走函数调用再解析tool_calls[0].arguments得到名单见 transcript_enrich_speaker.py用tenacity装饰器配置重试随机指数退避 610 秒、最多 4 次、对BadRequestError不重试10 个线程并发单文件处理完成后回写metadata[speaker]。6.3 时间桶切分transcript_enrich_bucket.pytranscript_enrich_bucket.py 把整段转录切成便于检索与摘要的「时间桶」默认SEGMENT_LENGTH_MINUTES 5可通过-m/--minutes覆盖启动脚本传入 3 分钟每个桶以startHH:MM:SS格式、seconds、标题、描述、说话人拼接文本构成一条记录关键细节默认MAX_TOKENS 2048当累计 token 数超过上限或时间超过桶长度时封桶同时按PERCENTAGE_OVERLAP 0.05把当前桶开头 5% 的文本追加到上一桶末尾平滑上下文衔接见 transcript_enrich_bucket.py使用tiktoken.encoding_for_model(gpt-4o-mini)做本地 token 计数为下一步摘要预留空间输出为folder/output/master_transcriptions.json。6.4 LLM 摘要transcript_enrich_summaries.pytranscript_enrich_summaries.py 为每个时间桶生成权威摘要系统提示要求「写一段权威的 60 词摘要避免以 This video 开头」通过client.responses.create调用gpt-5-minimax_output_tokens512超时 30 秒若返回状态不是completed脚本会告警并退出提示增大MAX_TOKENS异常兜底调用失败时直接用原文作为摘要保证流水线不中断输出前按(videoId, start 秒数)排序写出master_enriched.json。6.5 向量化transcript_enrich_embeddings.pytranscript_enrich_embeddings.py 是生成语义索引的关键一环使用AzureOpenAI客户端api_version2024-10-21调用client.embeddings.create(modelEMBEDDINGS_DEPLOYMENT_NAME, inputtext)取response.data[0].embedding作为ada_v2字段写入每条记录见 transcript_enrich_embeddings.py向量化前先经normalize_text清洗合并多余空白、去除换行、修复重复句点用tiktoken.get_encoding(cl100k_base)检查 token 数超过 8191 的文本直接跳过Embedding API 的输入上限已含ada_v2字段的记录会被跳过支持断点续跑6 个线程并发最终同样按(videoId, start)排序并回写master_enriched.json。6.6 轻量化transcript_enrich_lite.pytranscript_enrich_lite.py 做最后一步瘦身用字典推导剔除每条记录中的text与description字段仅保留标题、视频 ID、时间戳、摘要与ada_v2向量输出master_enriched_lite.json。这就是 embedding_index_3m.json 的最终形态——体积显著减小同时保留检索所需的全部语义信息。七、运行注意事项与排错要点顺序敏感六步必须按依赖顺序执行——transcript_enrich_summaries.py读取master_transcriptions.jsontranscript_enrich_embeddings.py读取master_enriched.jsontranscript_enrich_lite.py又读取前者。直接运行启动脚本可避免顺序错误。重试策略摘要与向量化两个脚本均配置了tenacity重试摘要退避 1045 秒、最多 20 次向量化退避 630 秒、最多 20 次对瞬时限流有较强韧性BadRequestError如上下文超长不重试。错误熔断transcript_enrich_speaker.py与transcript_enrich_summaries.py中累计错误超过 100 即退出避免无效空转。隐私与成本转录文本会被发送到 Azure OpenAI 与 Google 服务向量化按 token 计费建议先用小播放列表验证再全量执行。缺省值AZURE_OPENAI_MODEL_DEPLOYMENT_NAME缺省gpt-5-mini、AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT缺省text-embedding-ada-002若部署名不同请务必显式设置环境变量。八、产出衔接从索引到语义搜索流水线最终产出embedding_index_full_3m.json含原文与embedding_index_3m.json轻量两类索引文件。第 8 课搜索示例见 oai-solution.ipynb 与 aoai-solution.ipynb直接加载这类索引对用户查询做同样的 Embedding 编码后借助向量相似度配合scikit-learn/scipy检索最相关的视频片段——这正是 RAG 思想在视频内容检索上的落地先离线构建向量索引再在线做「查询向量化 最近邻检索」。掌握了本套脚本你就拥有了从原始视频内容到可检索向量索引的完整、可复用的生产链路。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考