generative-ai-for-beginners 第 08 课实战用 Python 构建 YouTube 转录数据的语义搜索索引管道【免费下载链接】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 仓库第 08 课《构建搜索应用》配套的转录数据准备脚本08-building-search-applications/scripts/README.md完整讲解如何将 YouTube 播放列表的视频转录下载下来经过说话人识别、按时间分桶、GPT 摘要、Embedding 向量化等一系列流水线处理最终产出可直接用于语义搜索的索引文件。读完本文你将掌握整套数据准备管道的资源准备、环境配置、脚本调用顺序与每一步的源码实现原理能够独立复现并运行为自己的视频内容构建向量检索数据集。一、这套脚本解决什么问题第 08 课《构建搜索应用》的目标是演示基于 OpenAI Embeddings 与 Function Calling 的语义搜索。而语义搜索的第一步——也是最繁琐的一步——就是准备可供向量化的文本数据需要把大量视频的转录文本抓取下来清洗、切分、加摘要、算向量最终生成一份embedding_index_xxx.json索引文件。本仓库的 scripts 目录 提供的正是这条完整的数据准备流水线共 6 个 Python 脚本 2 个一键编排脚本下载transcript_download.py —— 拉取 YouTube 播放列表内所有视频的转录文本VTT 格式说话人识别transcript_enrich_speaker.py —— 借助 OpenAI Function Calling 从标题、描述和首段转录中提取说话人姓名时间分桶transcript_enrich_bucket.py —— 将转录按指定分钟数切分成带时间戳的片段并加入首尾重叠以平滑上下文摘要增强transcript_enrich_summaries.py —— 用 GPT 为每个片段生成 60 词权威摘要向量化transcript_enrich_embeddings.py —— 为每个片段生成text-embedding-ada-002向量瘦身transcript_enrich_lite.py —— 移除大段文本字段产出精简版索引方便直接嵌入应用。该套脚本已在 Windows 11、macOS Ventura、Ubuntu 22.04及更新版本上完成测试。其最终产物正是仓库中已经预生成好的 embedding_index_3m.json3 分钟分桶索引课程 08 的 Python 与 TypeScript 示例应用即直接消费该文件做向量检索。二、前置条件创建 Azure OpenAI Service 资源运行脚本前需要准备一个 Azure OpenAI 服务资源用于两步工作一是调用 GPT 生成说话人与摘要文本生成二是调用 Embedding 模型计算向量。[!IMPORTANT] 官方建议先将 Azure CLI 升级到最新版本以确保与 OpenAI 服务兼容。1. 创建资源组az group create --name semantic-video-search --location eastus官方示例将资源组命名为semantic-video-search区域为 East US。你可以改名但如果更换了资源所在区域务必先查阅 Azure OpenAI 的模型可用性表确认你需要的模型尤其是text-embedding-ada-002与 GPT 系列在该区域可用。2. 创建 Azure OpenAI 资源az cognitiveservices account create --name semantic-video-openai --resource-group semantic-video-search \ --location eastus --kind OpenAI --sku s0--kind OpenAI指定账号类型为 OpenAI--sku s0是标准付费层级。3. 获取 Endpoint 与 API Keyaz 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 .key1两条命令分别通过jq提取出endpoint与key1这两个值稍后要写入环境变量。4. 部署所需模型需要部署两个模型Embedding 模型text-embedding-ada-002版本2或更高部署名为text-embedding-ada-002文本生成模型本仓库当前源码与英文原版 README 使用gpt-4o-mini部署名为gpt-4o-mini。印尼语版 README 仍保留旧示例gpt-35-turbo版本0613两个模型均可通过环境变量AZURE_OPENAI_MODEL_DEPLOYMENT_NAME指定源码默认值见 transcript_enrich_speaker.py 与 transcript_enrich_summaries.py。以text-embedding-ada-002与gpt-4o-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-4o-mini \ --model-name gpt-4o-mini \ --model-format OpenAI \ --sku-capacity 100 \ --sku-name Standard若沿用印尼语版文档中的旧示例可将第二个部署命令替换为az cognitiveservices account deployment create \ --name semantic-video-openai \ --resource-group semantic-video-search \ --deployment-name gpt-35-turbo \ --model-name gpt-35-turbo \ --model-version 0613 \ --model-format OpenAI \ --sku-capacity 100 \ --sku-name Standard注意--deployment-name必须与后续环境变量中的部署名保持一致因为脚本并不直接使用模型名而是用部署名去访问模型。三、环境变量配置脚本运行依赖 4 个环境变量缺一不可源码中直接通过os.environ[...]读取缺少即报错变量名用途AZURE_OPENAI_API_KEYAzure OpenAI 服务的 API KeyAZURE_OPENAI_ENDPOINTAzure OpenAI 服务的 EndpointAZURE_OPENAI_MODEL_DEPLOYMENT_NAME文本生成模型的部署名GOOGLE_DEVELOPER_API_KEYGoogle Developer API Key用于读取 YouTube 播放列表Windows 配置方式建议将变量加入当前用户的user环境变量Windows Start→Edit the system environment variables→Environment Variables→User variables选择你的用户名→New。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 keyLinux / macOS 配置方式将以下导出语句追加到~/.bashrc或~/.zshrc然后source使其生效export 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从源码看除上述 4 个必填变量外还有一个可选变量AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT用于指定 Embedding 模型部署名默认值为text-embedding-ada-002见 transcript_enrich_embeddings.py。如果你将 Embedding 模型部署成其他名字可以通过该变量覆盖。四、安装 Python 依赖运行环境要求Python 3.9 或更高版本。仓库已为这套脚本准备了 requirements.txt其中每个依赖的职责如下依赖版本约束在管道中的用途openai1.54.0,2.0.0调用 Azure OpenAIChat/Responses 与 Embeddings 均使用新版 SDKpandas2.1.0,3.0.0数据处理与后续分析matplotlib/plotly3.x / 5.16结果可视化供示例应用使用scipy/scikit-learn1.x向量相似度计算等科学计算tiktoken0.8.0,1.0.0分词计数用于控制片段长度不超过模型 Token 上限google-api-python-client2.98.0,3.0.0调用 YouTube Data API v3 枚举播放列表youtube-transcript-api0.6.1,1.0.0直接抓取视频转录文本rich13.5.2,14.0.0终端进度条展示tenacity8.2.3API 调用重试与退避安装步骤安装 git client如果尚未安装克隆本仓库到本地git clone https://github.com/GitHub_Trending/ge/generative-ai-for-beginners.git进入脚本目录08-building-search-applications/scripts创建 Python 虚拟环境在 Windowspython -m venv .venv在 macOS / Linuxpython3 -m venv .venv激活虚拟环境在 Windows.venv\Scripts\activate在 macOS / Linuxsource .venv/bin/activate安装依赖在 Windowspip install -r requirements.txt在 macOS / Linuxpip3 install -r requirements.txt五、一键运行编排脚本最省力的方式是直接运行编排脚本它会按正确顺序依次调用 6 个 Python 脚本并对输出文件做重命名。在 Windows.\prepare_transcripts_ai_show.ps1在 macOS / Linux./prepare_transcripts_ai_show.sh以 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脚本执行完毕后会在$TRANSCRIPT_FOLDER/output/下产出两个关键文件master_enriched.json→ 重命名为embedding_index_full_3m.json含完整文本的完整索引master_enriched_lite.json→ 重命名为embedding_index_3m.json移除大段文本的轻量索引。其中embedding_index_3m.json正是仓库中已随附的预生成索引文件见 embedding_index_3m.json。-m 3表示按3 分钟为一个片段分桶如果你想调整分桶粒度只需修改TRANSCRIPT_BUCKET_MINUTES即可。六、逐脚本源码剖析从下载到向量化的完整链路6.1 转录下载transcript_download.py该脚本接受-f/--folder输出目录与-p/--playlist播放列表 ID两个必填参数另有--verbose开启调试日志。核心流程用 Google Developer API 初始化 YouTube Data API v3 客户端见 transcript_download.py以maxResults50分页遍历播放列表全部视频将每个视频放入线程安全队列由40 个并发线程PROCESSING_THREADS 40消费调用YouTubeTranscriptApi.get_transcript(video_id)抓取转录每个视频产出两个文件videoId.json视频元数据title、description、speaker、videoId由 gen_metadata 写入videoId.json.vtt转录内容JSON 数组含text/start/duration字段若转录文件已存在则跳过断点续传友好抓取失败仅记录日志并跳过该视频不影响整体流程。需要注意该脚本需要GOOGLE_DEVELOPER_API_KEY环境变量transcript_download.py这个 Key 需要到 Google Cloud Console 申请并启用 YouTube Data API v3。6.2 说话人识别transcript_enrich_speaker.py该脚本为每个videoId.json追加speaker字段。其亮点在于使用OpenAI Function Calling做实体抽取见 transcript_enrich_speaker.py定义了一个名为get_speaker_name的 tool schema要求模型返回speakers字符串输入文本 视频标题 描述 转录前 3 分钟内容SEGMENT_MIN_LENGTH_MINUTES 3通过client.responses.create调用部署的文本生成模型tool_choice强制指定使用该函数使用tenacity装饰器实现指数退避重试wait_random_exponential(min6, max10)最多 4 次且BadRequestError不重试提取出的说话人以逗号分隔字符串写回元数据若未提取到speakers 则跳过该文件并打印---MISSING SPEAKER---。源码在调用模型前还会通过 clean_text 清洗文本去除换行、#39;实体、转场符号、双空格及[inaudible]标记。6.3 时间分桶transcript_enrich_bucket.py该脚本读取全部videoId.json.vtt将转录按时间切成片段并合并为output/master_transcriptions.json。关键设计见 transcript_enrich_bucket.pySEGMENT_LENGTH_MINUTES默认 5可通过-m/--minutes覆盖编排脚本传入 3控制片段时长PERCENTAGE_OVERLAP 0.05每个新片段会把上一个片段结尾 5% 的文本追加过来平滑上下文切换避免切分导致语义断裂append_text_to_previous_segmentMAX_TOKENS 2048用tiktoken编码模型取gpt-4o-mini实时统计 Token 数保证每个片段在时间与 Token 双重约束下不会超长——因为下一步摘要请求还要预留 1024 Token 的生成空间每个片段会带上startHH:MM:SS格式时间戳、seconds秒数、标题、描述、说话人等元数据并把这些上下文前缀拼入片段文本The speakers name is …、标题、描述确保每个片段自包含、可独立检索。6.4 摘要增强transcript_enrich_summaries.py该脚本读取master_transcriptions.json为每个片段调用文本生成模型生成摘要transcript_enrich_summaries.pySystem Prompt 要求模型充当视频的 AI 助理输出约 60 词的权威摘要且避免以 This video 开头生成参数temperature0.7、max_output_tokens512、top_p0.0检查响应状态若status ! completed则提示增加MAX_TOKENS后退出10 个并发线程处理tenacity配置了更激进的重试最多 20 次等待 10–45 秒摘要写入每个片段的summary字段输出到output/master_enriched.json并按videoId 起始时间排序。6.5 向量化transcript_enrich_embeddings.py这是把文本变成可检索向量的一步transcript_enrich_embeddings.py使用AzureOpenAI客户端api_version2024-10-21调用部署的text-embedding-ada-002模型通过 normalize_text 做正则清洗压缩连续空白、去掉..、. .等瑕疵用tiktoken的cl100k_base编码检查 Token 数超过 8191 Token 的片段直接跳过超出 Embedding 模型输入上限生成的 1536 维向量写入每个片段的ada_v2字段已含ada_v2的片段跳过支持断点续跑6 个并发线程 tenacity重试最多 20 次结果覆盖写回output/master_enriched.json。6.6 轻量索引transcript_enrich_lite.py最后一步用列表推导式剔除每个片段中的text与description字段只保留title、speaker、summary、start、videoId与ada_v2向量见 transcript_enrich_lite.py输出output/master_enriched_lite.json。这样索引体积大幅缩小适合直接随应用分发——仓库根目录与 scripts 目录下的embedding_index_3m.json即此类产物。七、产出物如何接入语义搜索应用完成上述流水线后你会得到文件内容用途output/master_enriched.json完整索引含原文、摘要、向量需保留全文场景output/embedding_index_3m.json轻量索引仅摘要 向量 元数据随应用分发的标准索引output/embedding_index_full_3m.json完整索引重命名后本地全量检索这份索引与第 08 课主文档08-building-search-applications/README.md中讲解的搜索应用配套使用应用加载索引后将用户查询文本同样编码为向量通过余弦相似度在ada_v2向量间做最近邻检索再结合 Function Calling 把检索结果组织成结构化答案。你可以替换-p参数指向自己的 YouTube 播放列表、调整-m分桶分钟数即可为任意视频内容生成专属的语义检索数据集。八、适用前提与注意事项账号与费用本管道重度依赖 Azure OpenAI 与 Google YouTube Data API运行前请确认账号已开通相应服务并了解计费方式网络与配额YouTube 转录抓取依赖公网访问大量视频 并发线程可能触发 API 限流脚本已内置重试与跳过机制但仍有概率漏抓建议检查日志模型可用性text-embedding-ada-002、gpt-4o-mini等模型的区域可用性以 Azure OpenAI 官方模型可用性表为准若部署名不同通过AZURE_OPENAI_MODEL_DEPLOYMENT_NAME与AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT两个环境变量适配Token 约束分桶脚本已将片段 Token 限制在 2048 以内Embedding 步骤又对超过 8191 Token 的片段做了兜底跳过自行修改分桶参数时请留意这两个上限结果重命名编排脚本会把master_enriched*.json重命名为带3m后缀的索引文件重跑前若文件已存在会被覆盖请做好备份。以上全部命令与配置均来自本仓库 08-building-search-applications/scripts 目录的真实文件你可以直接对照源码逐行验证并按需调整参数构建属于自己的语义搜索数据管道。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考