<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>tyron&apos;s page</title>
    <description>blog &amp; blog theme🤘</description>
    <link>https://titron.github.io/</link>
    <atom:link href="https://titron.github.io/feed.xml" rel="self" type="application/rss+xml"/>
    <pubDate>Thu, 09 Jul 2026 09:14:41 +0000</pubDate>
    <lastBuildDate>Thu, 09 Jul 2026 09:14:41 +0000</lastBuildDate>
    <generator>Jekyll v3.10.0</generator>
    
      <item>
        <title>DSP与音频混音mixer</title>
        <description>&lt;ul&gt;
  &lt;li&gt;content&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;一-音频数据相加与dsp实现&quot;&gt;一. 音频数据相加与dsp实现&lt;/h2&gt;

音频数据相加（常称为&lt;strong&gt;混音&lt;/strong&gt;，即 Mixing）是指&lt;strong&gt;将两个或多个音频信号在同一时间点上的采样值进行数学叠加&lt;/strong&gt;。此操作在数字音频处理、游戏引擎和语音识别 中非常常见。

&lt;h3 id=&quot;1-核心原理&quot;&gt;1. 核心原理&lt;/h3&gt;

数字音频本质上是一串连续的波形采样点数据（如 PCM 数据）。将两个音频相加，即对齐它们的时间轴，并将对应位置的采样值（Amplitude）相加： $S_{mix}(t) = S_1(t) + S_2(t)$

&lt;h3 id=&quot;2-常见实现方法与算法&quot;&gt;2. 常见实现方法与算法&lt;/h3&gt;

直接相加往往会导致数据溢出（削波失真），因此需要根据场景选择合适的算法：
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;直接求和法&lt;/strong&gt;：将同一声道的数值简单相加。优点是声音信息保留最完整，但混合的音轨越多，越容易超过音频格式的表示范围（例如 16-bit PCM 的 +32767），导致严重的爆音。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;归一化/平均加权法&lt;/strong&gt;：相加后除以音轨数量（或乘以一个权重系数）。例如双轨混合： $S_{mix} = \frac{S_1 + S_2}{2}$ 优点是绝对不会溢出，音质平滑；缺点是整体音量会变小。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;系数衰减法（非线性混音）&lt;/strong&gt;：为了防止极端情况下的溢出并保持音量，可以采用如 $S_{mix} = S_1 + S_2 - \frac{S_1 \times S_2}{MAX_VALUE}$ 的对数压缩算法。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;重叠相加法（Overlap-Add Method）&lt;/strong&gt;：在频域处理音频（如短时傅里叶变换 STFT）或平滑拼接不连续点时，通过对重叠区域的信号进行加权相加，能有效消除音频处理后的杂音和断层。&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;3-注意事项&quot;&gt;3. 注意事项&lt;/h3&gt;

在进行音频数据相加前，务必保证参与计算的音频具有相同的以下参数：
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;采样率（Sample Rate）&lt;/strong&gt;：例如 44.1 kHz 或 48 kHz。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;位深度（Bit Depth）&lt;/strong&gt;：例如 16 -bit 或 24 -bit。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;声道数（Channels）&lt;/strong&gt;：例如单声道（Mono）或立体声（Stereo）。&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;4-dsp数字信号处理中的经典应用&quot;&gt;4. DSP（数字信号处理）中的经典应用&lt;/h3&gt;

在 DSP 中，音频相加（加法器 $\bigoplus$）是构建复杂音频效果的最核心基础算子：

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;混音器（Mixer）：&lt;/strong&gt; 将 $N$ 路不同的音频信号乘以各自的增益权重后相加。&lt;/li&gt;
&lt;/ul&gt;

\[y[n] = g_1 \cdot x_1[n] + g_2 \cdot x_2[n] + \dots + g_N \cdot x_N[n]\]

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;延迟与回声效果器（Delay &amp;amp; Echo）：&lt;/strong&gt; 将当前信号与过去某个时间点的信号（延时信号）相加，创造出空间感。&lt;/li&gt;
&lt;/ul&gt;

\[y[n] = x[n] + g \cdot x[n-D]\]

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;数字滤波器（FIR / IIR Filter）：&lt;/strong&gt; 无论是低通、高通还是均衡器（EQ），其本质都是将不同延时阶段的采样点乘以系数后进行一连串的&lt;strong&gt;乘加组合（MAC 运算）&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;

\[y[n] = \sum_{k=0}^{M} b_k \cdot x[n-k] = b_0x[n] + b_1x[n-1] + b_2x[n-2] + \dots\]

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;主动降噪（ANC）：&lt;/strong&gt; 收集环境噪音 $x[n]$，通过 DSP 计算出反相信号 $-x[n]$，然后将两者相加实现相位抵消：&lt;/li&gt;
&lt;/ul&gt;

\[y[n] = x[n] + (-x[n]) = 0\]

&lt;h3 id=&quot;5-硬件级优化考量&quot;&gt;5. 硬件级优化考量&lt;/h3&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;MAC 单元：&lt;/strong&gt; DSP 芯片有专门的乘累加（Multiply-Accumulate）硬件单元，可以在一个时钟周期内完成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;A * B + C&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;定点数饱和指令：&lt;/strong&gt; 在定点数 DSP 芯片中，通常有硬件支持的饱和指令（如 ARM 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;__QADD&lt;/code&gt;），会自动让 $32767 + 1 = 32767$，防止数值翻转。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;SIMD 加速：&lt;/strong&gt; 现代 CPU 和 DSP 支持 SIMD（如 ARM 的 NEON，x86 的 SSE/AVX），可以在一个指令周期内同时让 4 个或 8 个采样点进行相加，极大提升多路混音性能。&lt;/li&gt;
&lt;/ol&gt;

&lt;h3 id=&quot;6-dsp-芯片级底层算法的实现考量&quot;&gt;6. DSP 芯片级/底层算法的实现考量&lt;/h3&gt;

当我们在嵌入式 DSP 芯片（如 TI 的 C6000 系列、ARM Cortex-M 系列的 CMSIS-DSP）或底层 C 语言中做音频相加时，必须考虑硬件特性：

&lt;h4 id=&quot;-mac-单元乘累加运算&quot;&gt;① MAC 单元（乘累加运算）&lt;/h4&gt;

DSP 芯片之所以处理音频快，是因为它有专门的 &lt;strong&gt;MAC (Multiply-Accumulate)&lt;/strong&gt; 硬件单元。它可以在一个时钟周期内完成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;A * B + C&lt;/code&gt; 的操作。因此，在 DSP 算法中，音频相加往往是和乘法（音量控制/系数）绑定在一起执行的。

&lt;h4 id=&quot;-固定小数点fixed-point-vs-浮点数floating-point&quot;&gt;② 固定小数点（Fixed-point） vs 浮点数（Floating-point）&lt;/h4&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;定点数 DSP（如 16-bit 整数）：&lt;/strong&gt; 算力要求低、芯片便宜，但极易&lt;strong&gt;溢出&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;
    &lt;strong&gt;DSP 优化手法：&lt;/strong&gt; 使用饱和加法（Saturated Add）指令。普通 CPU 中 $32767 + 1 = -32768$（符号位翻转导致巨恶劣爆音）；而 DSP 芯片通常有硬件支持的饱和指令（如 ARM 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;__QADD&lt;/code&gt;），会自动让 $32767 + 1 = 32767$，将失真降到最低。
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;浮点数 DSP（如 32-bit Float）：&lt;/strong&gt; 现代调音台、音频插件（VST）首选。动态范围极大（超过 $1500 \text{ dB}$），&lt;strong&gt;相加时几乎不需要担心溢出问题&lt;/strong&gt;，只需在最终输出（如 DAC 解码前）做一次硬剪切或限幅（Limiter）即可。&lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;-simd单指令多数据加速&quot;&gt;③ SIMD（单指令多数据）加速&lt;/h4&gt;

现代 CPU 和 DSP 支持 SIMD（如 ARM 的 NEON 指令集，x86 的 SSE/AVX）。
传统的加法是一个一个点相加；使用 SIMD 可以在一个指令周期内，&lt;strong&gt;同时让 4 个或 8 个采样点进行相加&lt;/strong&gt;，这让实时处理多路高采样率（如 $96\text{kHz} / 192\text{kHz}$）的音频混音变得极其轻松。

&lt;hr /&gt;

&lt;h2 id=&quot;二-处理实时流buffer数据时需要注意什么&quot;&gt;二. 处理实时流（buffer）数据时，需要注意什么？&lt;/h2&gt;

在处理实时流（Buffer）数据时，音频相加（混音）的最大挑战在于超低延迟要求以及防止突发性爆音（Clip）。

&lt;h3 id=&quot;1-实时流处理的核心步骤&quot;&gt;1. 实时流处理的核心步骤&lt;/h3&gt;

实时流通常以固定大小的缓冲区（Buffer / Block）为单位进行传输（如 256、512 或 1024 个采样点）。

&lt;ol&gt;
  &lt;li&gt;对齐时钟：确保所有输入流的 Buffer 块大小和采样率完全一致。&lt;/li&gt;
  &lt;li&gt;数据类型转换：将原始字节流（如 Int16 编码的 PCM）转换为浮点数（Float32）进行计算。&lt;/li&gt;
  &lt;li&gt;混合与增益控制：对各路数据进行加权求和。&lt;/li&gt;
  &lt;li&gt;限幅（Clipping/Limiting）：防止叠加后的数据超出安全范围。&lt;/li&gt;
  &lt;li&gt;还原编码：将 Float32 重新转回原始的 PCM 字节流输出。&lt;/li&gt;
&lt;/ol&gt;

&lt;h3 id=&quot;2-推荐的实时流混音算法&quot;&gt;2. 推荐的实时流混音算法&lt;/h3&gt;
在实时系统中，不建议使用简单的“平均法”（ (A+B)/2 ），因为这会导致每增加一路音频，整体音量就明显塌陷。推荐使用以下两种方式：
&lt;h3 id=&quot;方案-afloat32-累加--软限幅推荐&quot;&gt;方案 A：Float32 累加 + 软限幅（推荐）&lt;/h3&gt;
将所有输入 Buffer 转换成 [-1.0, 1.0] 的 float 数组，直接相加。在输出前通过 &lt;strong&gt;软限幅（Soft-Limiter / AGC）&lt;/strong&gt; 公式，既能保留音量，又能优雅地处理溢出，避免硬截断带来的刺耳咔哒声（Click）。
常用的实时软限幅公式（正切畸变）：
$f(x) = \tanh(x)$

或者更轻量、计算更快的公式：
$f(x) = \begin{cases} x &amp;amp; \vert{}x\vert{} \le 0.8 \cr 0.8 + 0.2 \times \tanh(\frac{\vert{}x\vert{}-0.8}{0.2}) &amp;amp; \vert{}x\vert{} &amp;gt; 0.8 \end{cases}$
&lt;h3 id=&quot;方案-b定点数int16直接饱和相加&quot;&gt;方案 B：定点数（Int16）直接饱和相加&lt;/h3&gt;
如果运行在嵌入式或对性能要求极高的底层系统（如 C/C++），可以使用硬件支持的 &lt;strong&gt;饱和加法（Saturated Add）&lt;/strong&gt; 。当相加结果超过 +32767 时自动等于 32767，超过 -32768 时自动等于 -32768。

&lt;ul&gt;
  &lt;li&gt;注：此方法在高爆音时仍会有轻微失真，但计算速度极快。&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;3-python-实时流混音示例基于-numpy&quot;&gt;3. Python 实时流混音示例（基于 NumPy）&lt;/h3&gt;
如果您的实时流是 PyAudio、WebRTC 或网络 Socket 传输的 bytes 缓冲，可以用以下高效的向量化代码进行混音：
&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;numpy&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;mix_live_buffers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer_a&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;bytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;buffer_b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;bytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;bytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;
    对两个 16-bit PCM 实时 Buffer 进行混合
    &quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;# 1. 将原始字节流高效转换为 Float32 数组 (范围 -1.0 到 1.0)
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;data_a&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;frombuffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer_a&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dtype&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;int16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;astype&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;float32&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;32768.0&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;data_b&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;frombuffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer_b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dtype&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;int16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;astype&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;float32&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;32768.0&lt;/span&gt;
    
    &lt;span class=&quot;c1&quot;&gt;# 2. 线性相加 (可在此处乘以权重，如 data_a * 0.8 + data_b * 0.5)
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;mixed_float&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;data_a&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;data_b&lt;/span&gt;
    
    &lt;span class=&quot;c1&quot;&gt;# 3. 实时软限幅 (Soft-Limiting)：防止硬截断爆音
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# 使用 np.tanh 可以平滑地将超出 [-1, 1] 的部分压缩回安全范围
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;mixed_clipped&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tanh&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mixed_float&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    
    &lt;span class=&quot;c1&quot;&gt;# 4. 还原为 16-bit PCM 字节流
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;mixed_pcm&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mixed_clipped&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;32767.0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;astype&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;int16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;mixed_pcm&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tobytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
&lt;h3 id=&quot;4-实时流混音的避坑指南&quot;&gt;4. 实时流混音的避坑指南&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;非阻塞对齐&lt;/strong&gt;：实时流经常面临“A 流到了，B 流还没到”的情况。必须设立一个环形缓冲区（Ring Buffer / FIFO Queue）。如果某一路断流，该路应当自动补零（静音），不能阻塞整个音频线程。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;延迟与抖动&lt;/strong&gt;：Buffer 越小延迟越低，但越容易卡顿。网络流混音前通常需要加入 Jitter Buffer（抖动缓冲区） 来平滑网络波动。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;淡入淡出（Fade）&lt;/strong&gt;：当某一路实时语音忽然加入或离开时，不要直接切断，应该在 Buffer 的前几毫秒做线性音量渐变，否则听众会听到明显的“啪”声。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;三-当用的编程语言是-c实时流是网络传输数据如何处理&quot;&gt;三. 当用的编程语言是 c，实时流是网络传输数据，如何处理？&lt;/h2&gt;

在 C 语言中处理网络传输的音频实时流（Buffer）混音，最核心的原则是高性能、零拷贝（或少拷贝）以及异步容错。由于网络流存在延迟和丢包，你不能直接把刚收到的网络包进行相加。
以下是标准的 C 语言工业级实时网络混音方案：

&lt;h3 id=&quot;1-核心架构设计&quot;&gt;1. 核心架构设计&lt;/h3&gt;
网络实时混音必须使用 Jitter Buffer（抖动缓冲区） 架构。不能让音频播放线程去等待网络接收线程。

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;graph LR
    %% 第一行逻辑
    Input(网络数据包 UDP/RTP) --&amp;gt; ThreadA[线程 A: 网络接收]
    ThreadA --&amp;gt; Write[写入对应的环形队列 Ring Buffer A/B]

    %% 第二行逻辑
    Timer([播放设备/定时器回调]) --&amp;gt; ThreadB[线程 B: 混音线程]
    Read{定时读取各队列并混音} &amp;lt;--&amp;gt; ThreadB
    ThreadB --&amp;gt; Output(输出音频)

    %% 虚线表示数据存储/交换关系
    Write -.-&amp;gt; Read
&lt;/code&gt;&lt;/pre&gt;
&lt;h3 id=&quot;2-核心-c-语言代码实现&quot;&gt;2. 核心 C 语言代码实现&lt;/h3&gt;
这里提供一个基于 &lt;strong&gt;Int16 PCM 格式&lt;/strong&gt;、使用 &lt;strong&gt;饱和加法（Saturated Add）&lt;/strong&gt; 的高效混音实现。饱和加法直接利用 CPU 边界判断，是 C 语言实时音频处理中最快速、最省算力的防爆音方法。
&lt;div class=&quot;language-c highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;cp&quot;&gt;#include&lt;/span&gt; &lt;span class=&quot;cpf&quot;&gt;&amp;lt;stdio.h&amp;gt;&lt;/span&gt;&lt;span class=&quot;cp&quot;&gt;
#include&lt;/span&gt; &lt;span class=&quot;cpf&quot;&gt;&amp;lt;stdint.h&amp;gt;&lt;/span&gt;&lt;span class=&quot;cp&quot;&gt;
#include&lt;/span&gt; &lt;span class=&quot;cpf&quot;&gt;&amp;lt;string.h&amp;gt;&lt;/span&gt;&lt;span class=&quot;cp&quot;&gt;
&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;// 饱和加法：防止 16位有符号整数溢出爆音&lt;/span&gt;
&lt;span class=&quot;kr&quot;&gt;inline&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;saturate_add&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sample1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sample2&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;mixed&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sample1&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sample2&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mixed&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;32767&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;  &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;32767&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mixed&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;32768&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;32768&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mixed&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;cm&quot;&gt;/**
 * 实时网络流混音函数
 * @param buffer_a    网络流A的缓冲区
 * @param buffer_b    网络流B的缓冲区
 * @param out_buffer  混音后的输出缓冲区
 * @param samples     本次 Buffer 的采样点数量（注意：不是字节数！字节数 = samples * 2）
 * @param weight_a    流A的音量权重 (0.0 到 1.0)
 * @param weight_b    流B的音量权重 (0.0 到 1.0)
 */&lt;/span&gt;
&lt;span class=&quot;kt&quot;&gt;void&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;mix_network_buffers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;buffer_a&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;buffer_b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; 
                         &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;out_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;size_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;samples&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; 
                         &lt;span class=&quot;kt&quot;&gt;float&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;weight_a&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;float&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;weight_b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; 
&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;// 如果某一路网络流断流（Buffer为空），直接处理另一路&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer_a&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;NULL&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;buffer_b&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;NULL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;memset&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;out_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;samples&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;sizeof&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;));&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;size_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;samples&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;++&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;// 1. 获取采样点，若断流则补静音(0)&lt;/span&gt;
        &lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s1&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;buffer_a&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer_a&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;weight_a&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
        &lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s2&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;buffer_b&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer_b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;weight_b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
        
        &lt;span class=&quot;c1&quot;&gt;// 2. 混合并进行饱和截断&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;out_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;saturate_add&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;s1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s2&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;3-网络流混音的-3-大致命坑与-c-语言解决方案&quot;&gt;3. 网络流混音的 3 大致命坑与 C 语言解决方案&lt;/h3&gt;

&lt;h3 id=&quot;-丢包与断流packet-loss--discontinuity&quot;&gt;① 丢包与断流（Packet Loss &amp;amp; Discontinuity）&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;现象&lt;/strong&gt;：网络抖动导致流 A 的数据包迟到，混音线程此时必须输出声音。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;对策&lt;/strong&gt;：如果网络环形缓冲区（Ring Buffer）为空，混音线程绝不能阻塞等待。必须直接视流 A 为全 0（静音）继续运行。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;高阶优化&lt;/strong&gt;：使用 PLC（丢包补偿）算法，在断流时复制前一个包的尾部并做淡出，避免声音突变。&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;-时钟异步与漂移clock-drift&quot;&gt;② 时钟异步与漂移（Clock Drift）&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;现象&lt;/strong&gt;：发送端 A、发送端 B 和你的接收端服务器，三者的声卡晶振频率有微小差异。运行几小时后，由于速率不同，某一路的 Buffer 会越来越大（积压延迟）或越来越小（卡顿）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;对策&lt;/strong&gt;：建立水线（Watermark）机制。&lt;/li&gt;
  &lt;li&gt;如果环形队列中积压的数据超过上限（如 &amp;gt; 60ms），则跳过（Drop）一小段采样。
    &lt;ul&gt;
      &lt;li&gt;如果积压数据过低（如 &amp;lt; 10ms），则复制/插值（Interpolate）一小段采样。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;-突发加入的啪声click-noise&quot;&gt;③ 突发加入的“啪”声（Click Noise）&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;现象&lt;/strong&gt;：当某路网络音频突然连上并开始说话时，信号从 0 突变到某个值，会产生刺耳的咔哒声。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;对策&lt;/strong&gt;：在流刚加入的第一个 Buffer（大约 5-10ms）应用淡入（Gain 从 0.0 渐变到 1.0）；在断开或静音时应用淡出（Gain 从 1.0 渐变到 0.0）。&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;4-推荐使用的开源-c-库&quot;&gt;4. 推荐使用的开源 C 库&lt;/h3&gt;
如果是在生产环境开发，不建议全部从零手写，可以集成以下成熟的轻量级 C 库：

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;WebRTC Audio Processing (Media Process)&lt;/strong&gt;：包含了世界上最强大的 Jitter Buffer、NetEQ（动态时钟对齐）以及 AGC（自动增益控制）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Opus Codec (libopus)&lt;/strong&gt;：如果你的网络流是压缩的，Opus 自带了丢包补偿（PLC）和重采样功能。&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;四-需要支持多路大于2路网络音频同时混合&quot;&gt;四. 需要支持多路（大于2路）网络音频同时混合&lt;/h2&gt;

在 C 语言中支持多路（大于2路）网络音频混音，最优雅且高效的架构是 &lt;strong&gt;“基线累加 + 单次饱和截断”&lt;/strong&gt; 。这意味着我们要把所有声道的采样点先加到一个高精度的变量（如 int32_t 或 float）中，最后统一做一次饱和处理，而不是两两两两相加，这样可以最大程度减少性能开销并降低失真。

以下是专为多路网络流设计的 C 语言解决方案。

&lt;h3 id=&quot;1-数据结构设计管理多路流&quot;&gt;1. 数据结构设计：管理多路流&lt;/h3&gt;
为了灵活应对 3 路、4 路甚至数十路音频，需要用结构体来管理每一路网络音频的状态（包含其缓冲区指针、当前音量权重、是否有效等）。
&lt;div class=&quot;language-c highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;cp&quot;&gt;#include&lt;/span&gt; &lt;span class=&quot;cpf&quot;&gt;&amp;lt;stdio.h&amp;gt;&lt;/span&gt;&lt;span class=&quot;cp&quot;&gt;
#include&lt;/span&gt; &lt;span class=&quot;cpf&quot;&gt;&amp;lt;stdint.h&amp;gt;&lt;/span&gt;&lt;span class=&quot;cp&quot;&gt;
#include&lt;/span&gt; &lt;span class=&quot;cpf&quot;&gt;&amp;lt;string.h&amp;gt;&lt;/span&gt;&lt;span class=&quot;cp&quot;&gt;
#include&lt;/span&gt; &lt;span class=&quot;cpf&quot;&gt;&amp;lt;stdlib.h&amp;gt;&lt;/span&gt;&lt;span class=&quot;cp&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;c1&quot;&gt;// 单路音频流的状态typedef struct {&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;// 指向当前需要混音的 Buffer（从该流的 RingBuffer 中取出）&lt;/span&gt;
    &lt;span class=&quot;kt&quot;&gt;float&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;volume&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;           &lt;span class=&quot;c1&quot;&gt;// 该路音频的音量权重 (0.0 ~ 1.0)&lt;/span&gt;
    &lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;is_active&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;          &lt;span class=&quot;c1&quot;&gt;// 该路当前是否有数据（0 = 断流/静音，1 = 有数据）&lt;/span&gt;
&lt;span class=&quot;err&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AudioStreamInput&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;2-多路混音核心-c-代码&quot;&gt;2. 多路混音核心 C 代码&lt;/h3&gt;
该实现采用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;int32_t&lt;/code&gt; 累加器。如果通道数极多（例如超过 100 路），为了彻底防止累加阶段就溢出，可以将累加器改为 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;float&lt;/code&gt;，这里以常规的多路网络会议/语音场景（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;int32_t&lt;/code&gt;）为例：
&lt;div class=&quot;language-c highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;// 高效饱和截断函数&lt;/span&gt;
&lt;span class=&quot;kr&quot;&gt;inline&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;saturate_add_multi&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sum&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sum&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;32767&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;  &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;32767&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sum&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;32768&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;32768&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sum&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;cm&quot;&gt;/**
 * 多路实时网络流混音
 * @param streams      输入流数组
 * @param stream_count 输入流的总路数
 * @param out_buffer   混音后的输出缓冲区
 * @param samples      本次 Buffer 的采样点数量
 */&lt;/span&gt;
&lt;span class=&quot;kt&quot;&gt;void&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;mix_multi_network_buffers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AudioStreamInput&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;streams&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;size_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;stream_count&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; 
                               &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;out_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;size_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;samples&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; 
&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;// 1. 遍历每一个采样点&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;size_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;samples&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;++&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;accumulator&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
        &lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;active_count&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;

        &lt;span class=&quot;c1&quot;&gt;// 2. 累加所有有效流在当前位置的采样点&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;size_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;j&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;j&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;stream_count&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;j&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;++&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;streams&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;j&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;is_active&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;streams&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;j&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;NULL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;c1&quot;&gt;// 应用音量权重并累加&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;accumulator&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int32_t&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;streams&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;j&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;streams&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;j&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;volume&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;active_count&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;++&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

        &lt;span class=&quot;c1&quot;&gt;// 3. 动态增益控制 (可选优化)&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;// 如果同时说话的人太多，声音会整体过载失真。&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;// 可以根据当前激发的流数量，进行轻微的衰减（例如下面这行代码，根据需要取消注释）：&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;// if (active_count &amp;gt; 2) { accumulator = (int32_t)(accumulator * 0.8f); }&lt;/span&gt;

        &lt;span class=&quot;c1&quot;&gt;// 4. 统一进行一次饱和截断并输出&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;out_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;saturate_add_multi&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;accumulator&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;3-工程化应用示例伪代码&quot;&gt;3. 工程化应用示例（伪代码）&lt;/h3&gt;
在实际的网络音频服务器或客户端中，你的混音线程通常会这样调用它：
&lt;div class=&quot;language-c highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;cp&quot;&gt;#define MAX_STREAMS 8
#define BUFFER_SAMPLES 480 // 假设 48kHz, 10ms 的数据
&lt;/span&gt;
&lt;span class=&quot;kt&quot;&gt;void&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;audio_mixer_thread_loop&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;AudioStreamInput&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;inputs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;MAX_STREAMS&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;];&lt;/span&gt;
    &lt;span class=&quot;kt&quot;&gt;int16_t&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;BUFFER_SAMPLES&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;];&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;while&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;running&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;// 1. 等待定时器（例如每 10ms 触发一次）&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;wait_for_10ms_timer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;

        &lt;span class=&quot;c1&quot;&gt;// 2. 从各自的 Jitter Buffer 中提取数据&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;MAX_STREAMS&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;++&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;// 从第 i 路用户的环形缓冲区读取 10ms 数据&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;// 如果提取失败（丢包/断流），ring_buffer_pop 应返回 NULL&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;inputs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ring_buffer_pop&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;user_ring_buffers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;BUFFER_SAMPLES&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;inputs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;volume&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;user_volumes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;];&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// 用户设定的音量&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;inputs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;is_active&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;inputs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;buffer&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;NULL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

        &lt;span class=&quot;c1&quot;&gt;// 3. 执行多路混音&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;mix_multi_network_buffers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;inputs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;MAX_STREAMS&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;BUFFER_SAMPLES&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;

        &lt;span class=&quot;c1&quot;&gt;// 4. 将混音后的数据推送到声卡播放，或者编码发给其他网络用户&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;send_to_speaker_or_network&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;output_buffer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;BUFFER_SAMPLES&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;4-多路网络混音的商业级设计要点&quot;&gt;4. 多路网络混音的商业级设计要点&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;发言者检测（VAD - Voice Activity Detection）&lt;/strong&gt;：
在大于 2 路的场景下（如 50 人的会议室），如果把所有人的网络流都强行加进来，即使不说话，他们各自背景里的 &lt;strong&gt;“底噪”叠加起来也会变成巨大的噪音&lt;/strong&gt; 。必须引入 VAD 算法，或者设置一个能量门限（Threshold）。当某路流的平均能量低于设定值时，直接将 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;is_active&lt;/code&gt; 设为 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0&lt;/code&gt;（视为静音），不参与混音。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;现代 CPU 性能加速（SIMD / AVX）&lt;/strong&gt;：
如果流的数量非常大，C 语言的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;for&lt;/code&gt; 循环可以通过编译优化加速。在 GCC / Clang 中编译时，请务必开启 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-O3&lt;/code&gt; 优化开关，编译器会自动将上述代码转化为 &lt;strong&gt;SIMD（单指令多数据）&lt;/strong&gt; 指令（如 Intel 的 AVX 或 ARM 的 NEON），实现 4 个或 8 个采样点同时相加，效率提升数倍。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;内存对齐&lt;/strong&gt;：
分配 Buffer 时，尽量使用支持字节对齐的函数（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;posix_memalign&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_aligned_malloc&lt;/code&gt;），这能让 CPU 在执行多路数据指针读取时达到最高速度。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

</description>
        <pubDate>Thu, 09 Jul 2026 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2026/07/09/audio_mixer_dsp/</link>
        <guid isPermaLink="true">https://titron.github.io/2026/07/09/audio_mixer_dsp/</guid>
        
        <category>knowledge,</category>
        
        <category>mixer,</category>
        
        <category>DSP</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>vscode 插件 Git Graph 使用(转)</title>
        <description>&lt;ul&gt;
  &lt;li&gt;content&lt;/li&gt;
&lt;/ul&gt;

&lt;a href=&quot;https://blog.csdn.net/weixin_55783373/article/details/119571301&quot;&gt;vscode 插件 Git Graph 使用(原)&lt;/a&gt;

gitgraph

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_001.png&quot; alt=&quot;gitgraph插件&quot; /&gt;

enable gitgraph

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_002.png&quot; alt=&quot;enable gitgraph插件&quot; /&gt;

fetch:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_fetch.png&quot; alt=&quot;gitgraph-fetch&quot; /&gt;

create branch:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_createbranch.png&quot; alt=&quot;gitgraph-createbranch&quot; /&gt;

checkout：

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_checkout.png&quot; alt=&quot;gitgraph-checkout&quot; /&gt;

commit or checkout:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_commit.png&quot; alt=&quot;gitgraph-commit&quot; /&gt;

push:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_push.png&quot; alt=&quot;gitgraph-push&quot; /&gt;

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_pushed.png&quot; alt=&quot;gitgraph-pushed&quot; /&gt;

pop stash:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_popstash.png&quot; alt=&quot;gitgraph-pop stash&quot; /&gt;

stash:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_stash.png&quot; alt=&quot;gitgraph-stash&quot; /&gt;

commit:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_committed.png&quot; alt=&quot;gitgraph-commit&quot; /&gt;

push to remote:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_push01.png&quot; alt=&quot;gitgraph-push to remote&quot; /&gt;

push branch:

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-06-30-gitgraph_pushbranch.png&quot; alt=&quot;gitgraph-push branch&quot; /&gt;
</description>
        <pubDate>Tue, 30 Jun 2026 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2026/06/30/gitgraph_vscode/</link>
        <guid isPermaLink="true">https://titron.github.io/2026/06/30/gitgraph_vscode/</guid>
        
        <category>knowledge,</category>
        
        <category>base,</category>
        
        <category>gitgraph,</category>
        
        <category>vscode</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>在 Ubuntu 22.04上搭建TFTP服务器和NFS服务器</title>
        <description>&lt;ul&gt;
  &lt;li&gt;content&lt;/li&gt;
&lt;/ul&gt;

在 Ubuntu 22.04 上搭建 &lt;strong&gt;TFTP 服务器&lt;/strong&gt;和 &lt;strong&gt;NFS 服务器&lt;/strong&gt;是嵌入式开发（如 Linux 内核调试、根文件系统挂载）的经典组合。以下是详细的搭建步骤：

&lt;hr /&gt;

&lt;h2 id=&quot;一-搭建-tftp-服务器&quot;&gt;一、 搭建 TFTP 服务器&lt;/h2&gt;

TFTP（简单文件传输协议）常用于在开发板启动时下载 Linux 内核镜像（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;uImage&lt;/code&gt;/&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;zImage&lt;/code&gt;）和设备树文件（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.dtb&lt;/code&gt;）。

&lt;h3 id=&quot;1-安装-tftp-相关软件&quot;&gt;1. 安装 TFTP 相关软件&lt;/h3&gt;

打开终端，执行以下命令安装 TFTP 服务端和客户端：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo apt update
sudo apt install tftpd-hpa tftp-hpa
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;2-创建-tftp-工作目录&quot;&gt;2. 创建 TFTP 工作目录&lt;/h3&gt;

创建一个用于存放传输文件的目录，并赋予最高权限，确保开发板可以正常读写：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo mkdir -p /home/tftpboot
sudo chmod 777 /home/tftpboot
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;3-修改配置文件&quot;&gt;3. 修改配置文件&lt;/h3&gt;

编辑 TFTP 的配置文件 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/etc/default/tftpd-hpa&lt;/code&gt;：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo nano /etc/default/tftpd-hpa
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

将内容修改为以下配置（主要修改 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TFTP_DIRECTORY&lt;/code&gt; 和 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TFTP_OPTIONS&lt;/code&gt;）：

Plaintext

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;TFTP_USERNAME=&quot;tftp&quot;
TFTP_DIRECTORY=&quot;/home/tftpboot&quot;
TFTP_ADDRESS=&quot;:69&quot;
TFTP_OPTIONS=&quot;--secure --create&quot;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  &lt;strong&gt;提示&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--create&lt;/code&gt; 参数允许客户端在服务器上创建新文件（即支持上传）。
&lt;/blockquote&gt;

&lt;h3 id=&quot;4-重启并检查服务&quot;&gt;4. 重启并检查服务&lt;/h3&gt;

保存退出后，重启 TFTP 服务并将其设置为开机自启：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo systemctl restart tftpd-hpa
sudo systemctl enable tftpd-hpa
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

检查服务状态，确保显示 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;active (running)&lt;/code&gt;：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo systemctl status tftpd-hpa
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;5-本地测试-tftp&quot;&gt;5. 本地测试 TFTP&lt;/h3&gt;

你可以通过本地回环测试来验证是否搭建成功：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;echo &quot;TFTP Test File&quot; &amp;gt; /home/tftpboot/test.txt
cd /tmp
tftp 127.0.0.1
# 进入 tftp 命令行后输入：
get test.txt
quit

# 查看 /tmp 目录下是否成功获取文件
cat test.txt
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;二-搭建-nfs-服务器&quot;&gt;二、 搭建 NFS 服务器&lt;/h2&gt;

NFS（网络文件系统）常用于将 Ubuntu 上的某个目录（如根文件系统 rootfs）挂载到开发板上，方便直接修改和调试代码而无需反复烧录。

&lt;h3 id=&quot;1-安装-nfs-服务端&quot;&gt;1. 安装 NFS 服务端&lt;/h3&gt;

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo apt install nfs-kernel-server
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;2-创建-nfs-共享目录&quot;&gt;2. 创建 NFS 共享目录&lt;/h3&gt;

创建一个用于挂载的文件目录：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo mkdir -p /home/nfsroot
sudo chmod 777 /home/nfsroot
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;3-配置共享目录权限&quot;&gt;3. 配置共享目录权限&lt;/h3&gt;

编辑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/etc/exports&lt;/code&gt; 文件来指定允许访问的客户端和权限：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo nano /etc/exports
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

在文件末尾添加以下内容（根据你的网络环境调整）：

Plaintext

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;/home/nfsroot *(rw,sync,no_root_squash,no_subtree_check)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;strong&gt;参数说明&lt;/strong&gt;：

&lt;ul&gt;
  &lt;li&gt;
    &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;*&lt;/code&gt;：代表允许所有的 IP 访问（在局域网开发环境中很方便。如果为了安全，可以写具体网段如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;119.168.1.0/24&lt;/code&gt;）。
  &lt;/li&gt;
  &lt;li&gt;
    &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rw&lt;/code&gt;：读写权限。
  &lt;/li&gt;
  &lt;li&gt;
    &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sync&lt;/code&gt;：资料同步写入内存与硬盘。
  &lt;/li&gt;
  &lt;li&gt;
    &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;no_root_squash&lt;/code&gt;：如果客户端使用的是 root 用户，则对该共享目录也拥有 root 权限（嵌入式开发必备）。
  &lt;/li&gt;
  &lt;li&gt;
    &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;no_subtree_check&lt;/code&gt;：不检查子目录权限，提高性能。
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;4-解决-ubuntu-2204-的-nfs-版本兼容问题重要-️&quot;&gt;4. 解决 Ubuntu 22.04 的 NFS 版本兼容问题（重要 ⚠️）&lt;/h3&gt;

&lt;blockquote&gt;
  &lt;strong&gt;避坑指南&lt;/strong&gt;：Ubuntu 22.04 默认&lt;strong&gt;关闭了 NFS v2 和 v3&lt;/strong&gt;，只开启了 NFS v4。但是很多老旧的开发板 U-Boot 或内核只支持 NFS v2 或 v3。如果你在挂载时遇到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Protocol not supported&lt;/code&gt; 或一直连不上，请按以下步骤开启 v3 支持。
&lt;/blockquote&gt;

&lt;ol&gt;
  &lt;li&gt;
    编辑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/etc/default/nfs-kernel-server&lt;/code&gt;：

    Bash

    &lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo nano /etc/default/nfs-kernel-server
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;

    修改或添加以下内容，确保不禁用 v3：

    Plaintext

    &lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;RPCNFSDOPTS=&quot;&quot;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;
    编辑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/etc/nfs.conf&lt;/code&gt;：

    Bash

    &lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo nano /etc/nfs.conf
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;

    找到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[nfsd]&lt;/code&gt; 标签，取消注释并修改 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;vers3&lt;/code&gt; 如下：

    Plaintext

    &lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;[nfsd]
vers3=y
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
&lt;/ol&gt;

&lt;h3 id=&quot;5-重启-nfs-服务&quot;&gt;5. 重启 NFS 服务&lt;/h3&gt;

配置完成后，重启相关服务并导出共享目录：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo systemctl restart rpcbind
sudo systemctl restart nfs-kernel-server
sudo systemctl enable nfs-kernel-server
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

使用以下命令查看当前生效的 NFS 共享目录：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;showmount -e
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

如果输出显示 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/home/nfsroot *&lt;/code&gt;，说明配置成功。

&lt;h3 id=&quot;6-本地测试-nfs&quot;&gt;6. 本地测试 NFS&lt;/h3&gt;

你可以尝试在本地挂载自己，验证服务是否正常：

Bash

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo mount -t nfs -o nfsvers=3 127.0.0.1:/home/nfsroot /mnt
# 检查是否成功挂载，随后卸载
ls /mnt
sudo umount /mnt
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;三-常见注意事项&quot;&gt;三、 常见注意事项&lt;/h2&gt;

&lt;ol&gt;
  &lt;li&gt;
    &lt;strong&gt;防火墙问题&lt;/strong&gt;：如果开发板依然无法连接，建议直接关闭 Ubuntu 的防火墙（仅限本地安全开发环境）：

    Bash

    &lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sudo ufw disable
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;strong&gt;IP 地址在同一网段&lt;/strong&gt;：请确保你的 Ubuntu 主机、Windows 宿主机（如果是虚拟机的话）以及开发板的 IP 地址处于&lt;strong&gt;同一个网段&lt;/strong&gt;，且能够互相 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ping&lt;/code&gt; 通。
  &lt;/li&gt;
&lt;/ol&gt;
</description>
        <pubDate>Thu, 18 Jun 2026 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2026/06/18/tftp_nfs_server_ubuntu_22.04/</link>
        <guid isPermaLink="true">https://titron.github.io/2026/06/18/tftp_nfs_server_ubuntu_22.04/</guid>
        
        <category>knowledge,</category>
        
        <category>base,</category>
        
        <category>tftp</category>
        
        <category>server,</category>
        
        <category>nfs</category>
        
        <category>server</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>Github上这款免费开源的Bash脚本教程</title>
        <description>
参考：
&lt;ol&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/bobbyiliev/introduction-to-bash-scripting&quot;&gt;introduction-to-bash-scripting&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://mp.weixin.qq.com/s?__biz=MzA3NzA2MDMyNA==&amp;amp;mid=2650374111&amp;amp;idx=1&amp;amp;sn=e4dd3d688fee6eb934f29663f7191718&amp;amp;chksm=86066b1e23a1c11213933970f27e0b3b0bd467bb566f33748ae5417b0caec8d6b425cb0722e5&amp;amp;mpshare=1&amp;amp;scene=1&amp;amp;srcid=0109pM7iKTBZrJkEuPEbl5ZS&amp;amp;sharer_shareinfo=d0f3d615a8a694f207b23bad5519394c&amp;amp;sharer_shareinfo_first=d0f3d615a8a694f207b23bad5519394c#rd&quot;&gt;挖到宝了！Github上这款免费开源的Bash脚本教程，让我从编程小白逆袭效率大神&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;strong&gt;content&lt;/strong&gt;

&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-01-23-script_guide_000-015.png&quot; alt=&quot;content 000~015&quot; /&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2026-01-23-script_guide_015-100.png&quot; alt=&quot;content 015~100&quot; /&gt;
</description>
        <pubDate>Fri, 23 Jan 2026 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2026/01/23/open_source_script_guide/</link>
        <guid isPermaLink="true">https://titron.github.io/2026/01/23/open_source_script_guide/</guid>
        
        <category>knowledge</category>
        
        <category>base</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>更改Linux/Unix 环境变量</title>
        <description>&lt;ul id=&quot;markdown-toc&quot;&gt;
  &lt;li&gt;&lt;a href=&quot;#方案-1使用-source-命令推荐&quot; id=&quot;markdown-toc-方案-1使用-source-命令推荐&quot;&gt;方案 1：使用 source 命令（推荐！）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#方案-2在-shell-配置文件中永久设置&quot; id=&quot;markdown-toc-方案-2在-shell-配置文件中永久设置&quot;&gt;方案 2：在 shell 配置文件中永久设置&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

情况一：在终端中直接设置（生效）
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;export&lt;/span&gt; PATH&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$PATH&lt;/span&gt;:/new/path
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

这是在当前 shell（父进程）中直接修改 PATH
后续所有命令都继承这个新 PATH

情况二：在脚本中设置（不生效）
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# setpath.sh&lt;/span&gt;
&lt;span class=&quot;nb&quot;&gt;export&lt;/span&gt; PATH&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$PATH&lt;/span&gt;:/new/path
&lt;span class=&quot;nb&quot;&gt;echo&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;$PATH&lt;/span&gt;  # 脚本内能看到新 PATH
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;./setpath.sh    # 或 bash setpath.sh
&lt;span class=&quot;nb&quot;&gt;echo&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;$PATH&lt;/span&gt;      # 终端中 PATH 未改变！
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;strong&gt;为什么？&lt;/strong&gt;

当你运行 ./setpath.sh 时，系统会启动一个子 shell 来执行脚本
脚本中的 export 只修改了子 shell 的环境变量
脚本执行完毕后，子 shell 退出，修改不会回传给父 shell（你的终端）

📌 Unix/Linux 的设计原则：子进程不能修改父进程的环境变量（安全机制）

✅ &lt;strong&gt;正确解决方案&lt;/strong&gt;
&lt;h3 id=&quot;方案-1使用-source-命令推荐&quot;&gt;方案 1：使用 source 命令（推荐！）&lt;/h3&gt;
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;source&lt;/span&gt; setpath.sh# 
或简写
. setpath.sh
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

原理：
&lt;ul&gt;
  &lt;li&gt;source 不会启动子 shell，而是在当前 shell 中逐行执行脚本&lt;/li&gt;
  &lt;li&gt;所有变量修改都作用于当前终端&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;方案-2在-shell-配置文件中永久设置&quot;&gt;方案 2：在 shell 配置文件中永久设置&lt;/h3&gt;
如果希望每次打开终端都生效，将 PATH 添加到配置文件：

对当前用户：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;echo&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;export PATH=&quot;$PATH:/opt/myapp/bin&quot;&apos;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&amp;gt;&lt;/span&gt; ~/.bashrc
&lt;span class=&quot;c&quot;&gt;# 或 ~/.zshrc（如果你用 zsh）&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

然后重载配置：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;source&lt;/span&gt; ~/.bashrc
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

对所有用户（需 root 权限）：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;sudo echo&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;export PATH=&quot;$PATH:/opt/myapp/bin&quot;&apos;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&amp;gt;&lt;/span&gt; /etc/environment
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
</description>
        <pubDate>Fri, 23 Jan 2026 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2026/01/23/change_PATH_script/</link>
        <guid isPermaLink="true">https://titron.github.io/2026/01/23/change_PATH_script/</guid>
        
        <category>knowledge</category>
        
        <category>base</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>构建自己的本地知识库</title>
        <description>&lt;ul id=&quot;markdown-toc&quot;&gt;
  &lt;li&gt;&lt;a href=&quot;#一整体架构完全本地化&quot; id=&quot;markdown-toc-一整体架构完全本地化&quot;&gt;一、整体架构（完全本地化）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#二关键组件与工具推荐开源--本地运行&quot; id=&quot;markdown-toc-二关键组件与工具推荐开源--本地运行&quot;&gt;二、关键组件与工具推荐（开源 + 本地运行）&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#1-文档解析与预处理&quot; id=&quot;markdown-toc-1-文档解析与预处理&quot;&gt;1. &lt;strong&gt;文档解析与预处理&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#2-文本分块chunking&quot; id=&quot;markdown-toc-2-文本分块chunking&quot;&gt;2. &lt;strong&gt;文本分块（Chunking）&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#3-文本向量化embedding&quot; id=&quot;markdown-toc-3-文本向量化embedding&quot;&gt;3. &lt;strong&gt;文本向量化（Embedding）&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#4-本地向量数据库&quot; id=&quot;markdown-toc-4-本地向量数据库&quot;&gt;4. &lt;strong&gt;本地向量数据库&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#5-本地大语言模型用于生成答案&quot; id=&quot;markdown-toc-5-本地大语言模型用于生成答案&quot;&gt;5. &lt;strong&gt;本地大语言模型（用于生成答案）&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#6-检索增强生成rag本地实现&quot; id=&quot;markdown-toc-6-检索增强生成rag本地实现&quot;&gt;6. &lt;strong&gt;检索增强生成（RAG）本地实现&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#7-用户界面可选&quot; id=&quot;markdown-toc-7-用户界面可选&quot;&gt;7. &lt;strong&gt;用户界面（可选）&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#三数据安全与隐私保障&quot; id=&quot;markdown-toc-三数据安全与隐私保障&quot;&gt;三、数据安全与隐私保障&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#四简易搭建流程示例&quot; id=&quot;markdown-toc-四简易搭建流程示例&quot;&gt;四、简易搭建流程（示例）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#五进阶建议&quot; id=&quot;markdown-toc-五进阶建议&quot;&gt;五、进阶建议&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#总结&quot; id=&quot;markdown-toc-总结&quot;&gt;总结&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-第一步准备工作&quot; id=&quot;markdown-toc--第一步准备工作&quot;&gt;🧰 第一步：准备工作&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#11-安装-python建议-310-或-311&quot; id=&quot;markdown-toc-11-安装-python建议-310-或-311&quot;&gt;1.1 安装 Python（建议 3.10 或 3.11）&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#12-创建项目目录&quot; id=&quot;markdown-toc-12-创建项目目录&quot;&gt;1.2 创建项目目录&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#13-创建虚拟环境推荐&quot; id=&quot;markdown-toc-13-创建虚拟环境推荐&quot;&gt;1.3 创建虚拟环境（推荐）&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#14-安装依赖包&quot; id=&quot;markdown-toc-14-安装依赖包&quot;&gt;1.4 安装依赖包&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-第二步准备你的知识文档&quot; id=&quot;markdown-toc--第二步准备你的知识文档&quot;&gt;📁 第二步：准备你的知识文档&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-第三步编写文档加载与分块脚本&quot; id=&quot;markdown-toc--第三步编写文档加载与分块脚本&quot;&gt;🧩 第三步：编写文档加载与分块脚本&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-第四步构建本地向量数据库使用-bge-中文嵌入模型&quot; id=&quot;markdown-toc--第四步构建本地向量数据库使用-bge-中文嵌入模型&quot;&gt;🧠 第四步：构建本地向量数据库（使用 BGE 中文嵌入模型）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-第五步本地语义检索不依赖大模型直接返回相关段落&quot; id=&quot;markdown-toc--第五步本地语义检索不依赖大模型直接返回相关段落&quot;&gt;🔍 第五步：本地语义检索（不依赖大模型，直接返回相关段落）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-第六步可选使用本地大模型生成答案rag&quot; id=&quot;markdown-toc--第六步可选使用本地大模型生成答案rag&quot;&gt;🤖 第六步（可选）：使用本地大模型生成答案（RAG）&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#61-安装-ollamahttpsollamacom&quot; id=&quot;markdown-toc-61-安装-ollamahttpsollamacom&quot;&gt;6.1 安装 Ollama（https://ollama.com/）&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#62-拉取本地中文模型首次需要联网之后离线可用&quot; id=&quot;markdown-toc-62-拉取本地中文模型首次需要联网之后离线可用&quot;&gt;6.2 拉取本地中文模型（首次需要联网，之后离线可用）&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#63-创建-rag-查询脚本rag_querypy&quot; id=&quot;markdown-toc-63-创建-rag-查询脚本rag_querypy&quot;&gt;6.3 创建 RAG 查询脚本：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rag_query.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-隐私与安全说明&quot; id=&quot;markdown-toc--隐私与安全说明&quot;&gt;🔒 隐私与安全说明&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-附录完全离线使用提前下载模型&quot; id=&quot;markdown-toc--附录完全离线使用提前下载模型&quot;&gt;📌 附录：完全离线使用（提前下载模型）&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#a-下载嵌入模型&quot; id=&quot;markdown-toc-a-下载嵌入模型&quot;&gt;A. 下载嵌入模型&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#b-下载-ollama-模型后复制到目标机器&quot; id=&quot;markdown-toc-b-下载-ollama-模型后复制到目标机器&quot;&gt;B. 下载 Ollama 模型后复制到目标机器&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-总结&quot; id=&quot;markdown-toc--总结&quot;&gt;✅ 总结&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#需要图形界面以及自动监控文档更新&quot; id=&quot;markdown-toc-需要图形界面以及自动监控文档更新&quot;&gt;需要图形界面以及自动监控文档更新&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#-最终目标架构&quot; id=&quot;markdown-toc--最终目标架构&quot;&gt;✅ 最终目标架构&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#第一步安装额外依赖&quot; id=&quot;markdown-toc-第一步安装额外依赖&quot;&gt;第一步：安装额外依赖&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#第二步实现自动监控文档更新--增量更新向量库&quot; id=&quot;markdown-toc-第二步实现自动监控文档更新--增量更新向量库&quot;&gt;第二步：实现“自动监控文档更新 + 增量更新向量库”&lt;/a&gt;        &lt;ul&gt;
          &lt;li&gt;&lt;a href=&quot;#创建-auto_updaterpy&quot; id=&quot;markdown-toc-创建-auto_updaterpy&quot;&gt;创建 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;auto_updater.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
        &lt;/ul&gt;
      &lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#第三步改造-build_vector_dbpy支持被调用&quot; id=&quot;markdown-toc-第三步改造-build_vector_dbpy支持被调用&quot;&gt;第三步：改造 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;build_vector_db.py&lt;/code&gt;（支持被调用）&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#第四步创建图形界面streamlit&quot; id=&quot;markdown-toc-第四步创建图形界面streamlit&quot;&gt;第四步：创建图形界面（Streamlit）&lt;/a&gt;        &lt;ul&gt;
          &lt;li&gt;&lt;a href=&quot;#创建-apppy&quot; id=&quot;markdown-toc-创建-apppy&quot;&gt;创建 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
        &lt;/ul&gt;
      &lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#第五步启动完整系统&quot; id=&quot;markdown-toc-第五步启动完整系统&quot;&gt;第五步：启动完整系统&lt;/a&gt;        &lt;ul&gt;
          &lt;li&gt;&lt;a href=&quot;#创建启动脚本-startshlinuxmacos或-startbatwindows&quot; id=&quot;markdown-toc-创建启动脚本-startshlinuxmacos或-startbatwindows&quot;&gt;创建启动脚本 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.sh&lt;/code&gt;（Linux/macOS）或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.bat&lt;/code&gt;（Windows）&lt;/a&gt;            &lt;ul&gt;
              &lt;li&gt;&lt;a href=&quot;#startsh&quot; id=&quot;markdown-toc-startsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.sh&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
              &lt;li&gt;&lt;a href=&quot;#windows-startbat&quot; id=&quot;markdown-toc-windows-startbat&quot;&gt;Windows (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.bat&lt;/code&gt;)&lt;/a&gt;&lt;/li&gt;
            &lt;/ul&gt;
          &lt;/li&gt;
        &lt;/ul&gt;
      &lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#第六步使用说明&quot; id=&quot;markdown-toc-第六步使用说明&quot;&gt;第六步：使用说明&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#-可选增强&quot; id=&quot;markdown-toc--可选增强&quot;&gt;🔧 可选增强&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#-总结-1&quot; id=&quot;markdown-toc--总结-1&quot;&gt;✅ 总结&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#在-ingestpy-中启用-unstructured-的-pdfdocx-loader&quot; id=&quot;markdown-toc-在-ingestpy-中启用-unstructured-的-pdfdocx-loader&quot;&gt;在 ingest.py 中启用 Unstructured 的 PDF/DOCX loader&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#-第一步安装必要的本地依赖&quot; id=&quot;markdown-toc--第一步安装必要的本地依赖&quot;&gt;✅ 第一步：安装必要的本地依赖&lt;/a&gt;        &lt;ul&gt;
          &lt;li&gt;&lt;a href=&quot;#11-安装-python-依赖&quot; id=&quot;markdown-toc-11-安装-python-依赖&quot;&gt;1.1 安装 Python 依赖&lt;/a&gt;&lt;/li&gt;
          &lt;li&gt;&lt;a href=&quot;#12-安装系统级依赖windows&quot; id=&quot;markdown-toc-12-安装系统级依赖windows&quot;&gt;1.2 安装系统级依赖（Windows）&lt;/a&gt;            &lt;ul&gt;
              &lt;li&gt;&lt;a href=&quot;#1安装-tesseract-ocr用于-pdf-中扫描图像的文字识别&quot; id=&quot;markdown-toc-1安装-tesseract-ocr用于-pdf-中扫描图像的文字识别&quot;&gt;（1）安装 &lt;strong&gt;Tesseract OCR&lt;/strong&gt;（用于 PDF 中扫描图像的文字识别）&lt;/a&gt;&lt;/li&gt;
              &lt;li&gt;&lt;a href=&quot;#2安装-poppler用于-pdf2image&quot; id=&quot;markdown-toc-2安装-poppler用于-pdf2image&quot;&gt;（2）安装 &lt;strong&gt;Poppler&lt;/strong&gt;（用于 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pdf2image&lt;/code&gt;）&lt;/a&gt;&lt;/li&gt;
            &lt;/ul&gt;
          &lt;/li&gt;
        &lt;/ul&gt;
      &lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#-第二步修改-ingestpy-启用-pdfdocx-加载器&quot; id=&quot;markdown-toc--第二步修改-ingestpy-启用-pdfdocx-加载器&quot;&gt;✅ 第二步：修改 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt; 启用 PDF/DOCX 加载器&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#-第三步验证配置确保无网络请求&quot; id=&quot;markdown-toc--第三步验证配置确保无网络请求&quot;&gt;✅ 第三步：验证配置（确保无网络请求）&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#-第四步可选提高-pdf-解析质量&quot; id=&quot;markdown-toc--第四步可选提高-pdf-解析质量&quot;&gt;✅ 第四步（可选）：提高 PDF 解析质量&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#-文件目录示例&quot; id=&quot;markdown-toc--文件目录示例&quot;&gt;✅ 文件目录示例&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#️-常见问题解决&quot; id=&quot;markdown-toc-️-常见问题解决&quot;&gt;⚠️ 常见问题解决&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#-总结-2&quot; id=&quot;markdown-toc--总结-2&quot;&gt;✅ 总结&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

在“仅用于自己查询、不上传任何信息到云端”的前提下，构建本地知识库的核心目标是：&lt;strong&gt;完全离线、数据安全、高效检索&lt;/strong&gt;。下面是一个系统化的构建方案，涵盖工具选择、数据处理、检索方式等关键环节：

&lt;h3 id=&quot;一整体架构完全本地化&quot;&gt;一、整体架构（完全本地化）&lt;/h3&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;[本地文档/数据源]  
       ↓  
[文档解析 &amp;amp; 向量化] → [本地向量数据库]  
       ↓  
[本地大模型（LLM）] ←→ [本地检索系统]  
       ↓  
[用户界面 / 查询入口]
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

所有组件均运行在你的个人电脑或局域网服务器上，无需联网。

&lt;hr /&gt;

&lt;h3 id=&quot;二关键组件与工具推荐开源--本地运行&quot;&gt;二、关键组件与工具推荐（开源 + 本地运行）&lt;/h3&gt;

&lt;h4 id=&quot;1-文档解析与预处理&quot;&gt;1. &lt;strong&gt;文档解析与预处理&lt;/strong&gt;&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;支持格式：PDF、Word、TXT、Markdown、网页快照、笔记（如 Obsidian/Logseq 导出）等。&lt;/li&gt;
  &lt;li&gt;工具：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Unstructured&lt;/code&gt;（Python 库）：智能解析多种文档。&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PyPDF2&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pdfplumber&lt;/code&gt;：处理 PDF。&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BeautifulSoup&lt;/code&gt;：解析 HTML。&lt;/li&gt;
      &lt;li&gt;对于 Obsidian 等笔记系统，可直接读取 Markdown 文件。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;2-文本分块chunking&quot;&gt;2. &lt;strong&gt;文本分块（Chunking）&lt;/strong&gt;&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;将长文档切分为适合检索的片段（如 300–500 字）。&lt;/li&gt;
  &lt;li&gt;可使用重叠分块（overlap）保留上下文。&lt;/li&gt;
  &lt;li&gt;工具：LangChain 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RecursiveCharacterTextSplitter&lt;/code&gt; 或自定义逻辑。&lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;3-文本向量化embedding&quot;&gt;3. &lt;strong&gt;文本向量化（Embedding）&lt;/strong&gt;&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;将文本转换为向量（用于语义搜索）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;推荐本地嵌入模型&lt;/strong&gt;（无需联网）：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BAAI/bge-small-zh-v1.5&lt;/code&gt;（中文优化，轻量高效）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;m3e-small&lt;/code&gt;（中文社区常用）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;all-MiniLM-L6-v2&lt;/code&gt;（英文/多语言，极小）&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sentence-transformers&lt;/code&gt; 库本地加载模型。&lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;4-本地向量数据库&quot;&gt;4. &lt;strong&gt;本地向量数据库&lt;/strong&gt;&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;存储和检索向量，支持相似性搜索。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;推荐&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;strong&gt;ChromaDB&lt;/strong&gt;：轻量、嵌入式、Python 友好，支持持久化。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;FAISS&lt;/strong&gt;（Facebook）：高效，适合静态知识库。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;Qdrant&lt;/strong&gt;（可本地运行）：功能更强，支持过滤、多向量等。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;SQLite + Vector 扩展&lt;/strong&gt;（如 sqlite-vss）：极简方案。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
  ✅ 所有数据库均可配置为仅保存在本地磁盘，不联网。
&lt;/blockquote&gt;

&lt;h4 id=&quot;5-本地大语言模型用于生成答案&quot;&gt;5. &lt;strong&gt;本地大语言模型（用于生成答案）&lt;/strong&gt;&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;可选：如果你希望模型基于检索到的内容“总结”或“回答”，而非仅返回原文。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;推荐本地 LLM&lt;/strong&gt;（7B 以下可在消费级 GPU 或 CPU 运行）：
    &lt;ul&gt;
      &lt;li&gt;&lt;strong&gt;中文&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Qwen1.5-4B-Chat&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Yi-1.5-6B-Chat&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DeepSeek-Coder&lt;/code&gt;（若含代码）&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;多语言/英文&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Mistral-7B&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Phi-3-mini&lt;/code&gt;（微软，性能强且小）&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;运行框架&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Ollama&lt;/code&gt;（最简单，一键运行模型）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LM Studio&lt;/code&gt;（图形界面，支持聊天和 API）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llama.cpp&lt;/code&gt;（CPU 友好，量化后可在普通笔记本运行）&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;6-检索增强生成rag本地实现&quot;&gt;6. &lt;strong&gt;检索增强生成（RAG）本地实现&lt;/strong&gt;&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;流程：
    &lt;ol&gt;
      &lt;li&gt;用户提问 → 用本地嵌入模型转为向量。&lt;/li&gt;
      &lt;li&gt;在本地向量库中搜索最相关的 3–5 个文本块。&lt;/li&gt;
      &lt;li&gt;将问题 + 检索结果拼接为提示（prompt），送入本地 LLM 生成答案。&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
  &lt;li&gt;可用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LangChain&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LlamaIndex&lt;/code&gt; 构建本地 RAG 流程（设置 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;offline=True&lt;/code&gt;，禁用网络）。&lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;7-用户界面可选&quot;&gt;7. &lt;strong&gt;用户界面（可选）&lt;/strong&gt;&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;命令行（最简单）&lt;/li&gt;
  &lt;li&gt;Web 界面（如用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Gradio&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Streamlit&lt;/code&gt; 快速搭建本地 UI）&lt;/li&gt;
  &lt;li&gt;Obsidian 插件（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Smart Connections&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Local LLM&lt;/code&gt; 集成）&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h3 id=&quot;三数据安全与隐私保障&quot;&gt;三、数据安全与隐私保障&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;所有数据存储在本地磁盘（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;~/my_knowledge_base/&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;向量数据库文件（如 Chroma 的 persist directory）也保存在本地。&lt;/li&gt;
  &lt;li&gt;使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ollama serve&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;lmstudio&lt;/code&gt; 时，确保禁用远程访问（默认仅 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;localhost&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;可对敏感数据加密（如使用 VeraCrypt 创建加密卷存放知识库）。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h3 id=&quot;四简易搭建流程示例&quot;&gt;四、简易搭建流程（示例）&lt;/h3&gt;

&lt;ol&gt;
  &lt;li&gt;安装 Python 和必要库：
    &lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;langchain chromadb sentence-transformers unstructured
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;下载中文嵌入模型（首次运行自动下载到本地）：
    &lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;sentence_transformers&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SentenceTransformer&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;model&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SentenceTransformer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;BAAI/bge-small-zh-v1.5&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;构建向量库（以 Chroma 为例）：
    &lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_chroma&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.embeddings&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;BAAI/bge-small-zh-v1.5&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;from_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;your_docs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;embedding&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;persist_directory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;本地查询（无需 LLM 也可直接返回相关段落）：
    &lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;results&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;similarity_search&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;你的问题&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;k&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;results&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;若需 LLM 生成答案，用 Ollama 启动模型：
    &lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ollama pull qwen:4b
ollama run qwen:4b
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
    再通过 API 或 LangChain 调用。
  &lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h3 id=&quot;五进阶建议&quot;&gt;五、进阶建议&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;定期备份&lt;/strong&gt;：知识库文件（向量库 + 原始文档）定期加密备份。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;增量更新&lt;/strong&gt;：支持新增/删除文档后更新向量库。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;多模态扩展&lt;/strong&gt;：未来可加入图片 OCR（Tesseract + PaddleOCR 本地运行）。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h3 id=&quot;总结&quot;&gt;总结&lt;/h3&gt;

✅ 完全本地&lt;br /&gt;
✅ 无数据上传&lt;br /&gt;
✅ 中文友好&lt;br /&gt;
✅ 开源免费&lt;br /&gt;
✅ 可在普通电脑运行（尤其使用 4B 以下模型 + Chroma/FAISS）

只要你有一台个人电脑（最好是 16GB+ 内存，如有独立 GPU 更佳），就可以搭建一个&lt;strong&gt;私密、安全、高效&lt;/strong&gt;的个人知识库系统。

&lt;hr /&gt;

以下是一个&lt;strong&gt;完全本地化、无需联网、不上传任何数据到云端&lt;/strong&gt;的中文个人知识库构建教程，使用开源工具和模型。我们将使用：

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;文档格式&lt;/strong&gt;：本地 Markdown / TXT / PDF（以 Markdown 为例）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;嵌入模型&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BAAI/bge-small-zh-v1.5&lt;/code&gt;（中文优化，本地运行）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;向量数据库&lt;/strong&gt;：ChromaDB（轻量、支持持久化）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;大模型（可选）&lt;/strong&gt;：Qwen 4B（通过 Ollama 本地运行）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;框架&lt;/strong&gt;：Python + LangChain（仅用于流程编排，不联网）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;运行环境&lt;/strong&gt;：Windows / macOS / Linux 均可（推荐 Python 3.10+）&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第一步准备工作&quot;&gt;🧰 第一步：准备工作&lt;/h2&gt;

&lt;h3 id=&quot;11-安装-python建议-310-或-311&quot;&gt;1.1 安装 Python（建议 3.10 或 3.11）&lt;/h3&gt;
从 &lt;a href=&quot;https://www.python.org/downloads/&quot;&gt;python.org&lt;/a&gt; 下载并安装。

&lt;h3 id=&quot;12-创建项目目录&quot;&gt;1.2 创建项目目录&lt;/h3&gt;
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;mkdir&lt;/span&gt; ~/local_knowledge_base
&lt;span class=&quot;nb&quot;&gt;cd&lt;/span&gt; ~/local_knowledge_base
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;13-创建虚拟环境推荐&quot;&gt;1.3 创建虚拟环境（推荐）&lt;/h3&gt;
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;python &lt;span class=&quot;nt&quot;&gt;-m&lt;/span&gt; venv venv
&lt;span class=&quot;nb&quot;&gt;source &lt;/span&gt;venv/bin/activate      &lt;span class=&quot;c&quot;&gt;# macOS/Linux&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;# 或&lt;/span&gt;
venv&lt;span class=&quot;se&quot;&gt;\S&lt;/span&gt;cripts&lt;span class=&quot;se&quot;&gt;\a&lt;/span&gt;ctivate         &lt;span class=&quot;c&quot;&gt;# Windows&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;14-安装依赖包&quot;&gt;1.4 安装依赖包&lt;/h3&gt;
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;langchain &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            langchain-community &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            langchain-chroma &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            chromadb &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            sentence-transformers &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            unstructured &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            unstructured[local-inference] &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            pdf2image &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            PyPDF2 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            ollama &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
            python-dotenv
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  ⚠️ 如果你&lt;strong&gt;不需要 PDF 解析&lt;/strong&gt;，可跳过 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pdf2image&lt;/code&gt; 和 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PyPDF2&lt;/code&gt;。

  ⚠️ 首次运行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sentence-transformers&lt;/code&gt; 会&lt;strong&gt;自动下载模型到本地缓存&lt;/strong&gt;（约 130MB），但&lt;strong&gt;不需要联网之后也能用&lt;/strong&gt;。如果你完全不能联网，请提前在有网环境下载好模型（见附录）。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第二步准备你的知识文档&quot;&gt;📁 第二步：准备你的知识文档&lt;/h2&gt;

在项目目录下创建一个 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docs/&lt;/code&gt; 文件夹，放入你的文档，例如：

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;local_knowledge_base/
├── docs/
│   ├── note1.md
│   ├── note2.md
│   └── my_book_summary.txt
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  支持格式：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.txt&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.md&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.pdf&lt;/code&gt;（后续可扩展）
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第三步编写文档加载与分块脚本&quot;&gt;🧩 第三步：编写文档加载与分块脚本&lt;/h2&gt;

创建文件：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# ingest.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;os&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.document_loaders&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;DirectoryLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;TextLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;UnstructuredMarkdownLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;PyPDFLoader&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_text_splitters&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RecursiveCharacterTextSplitter&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# 配置路径
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./docs&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;加载所有支持的文档&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# 加载 .txt 文件
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;txt_loader&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DirectoryLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;glob&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;*.txt&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;loader_cls&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TextLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;loader_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;encoding&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;utf-8&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;extend&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;txt_loader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;load&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# 加载 .md 文件
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;md_loader&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DirectoryLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;glob&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;*.md&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;loader_cls&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;UnstructuredMarkdownLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;extend&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;md_loader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;load&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# 加载 .pdf 文件（可选）
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# pdf_loader = DirectoryLoader(DOCS_DIR, glob=&quot;*.pdf&quot;, loader_cls=PyPDFLoader)
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# documents.extend(pdf_loader.load())
&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 共加载 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; 个文档片段&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;将文档切分为小块&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;text_splitter&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RecursiveCharacterTextSplitter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;chunk_size&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;500&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;chunk_overlap&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;50&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;length_function&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;is_separator_regex&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;text_splitter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 切分为 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; 个文本块&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;__name__&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;__main__&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# 保存到临时文件（用于下一步嵌入）
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;makedirs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;exist_ok&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;with&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;open&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;join&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;chunks.txt&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;w&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;encoding&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;utf-8&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;chunk&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;enumerate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;--- Chunk &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; ---&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunk&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;page_content&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 文本块已保存（供调试）&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

运行：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;python ingest.py
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  ✅ 此时会在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chroma_db/chunks.txt&lt;/code&gt; 中看到切分后的文本（可选，仅调试用）
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第四步构建本地向量数据库使用-bge-中文嵌入模型&quot;&gt;🧠 第四步：构建本地向量数据库（使用 BGE 中文嵌入模型）&lt;/h2&gt;

创建文件：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;build_vector_db.py&lt;/code&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# build_vector_db.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_chroma&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.embeddings&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;ingest&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;os&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# 嵌入模型配置（完全本地）
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;BAAI/bge-small-zh-v1.5&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;device&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;cpu&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;          &lt;span class=&quot;c1&quot;&gt;# 若有 GPU 可改为 &apos;cuda&apos;
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;normalize_embeddings&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# BGE 推荐设置
&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;query_instruction&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;为这个句子生成表示以用于检索相关文章：&quot;&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# BGE 中文模型推荐 query 指令
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;build_vector_db&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🔍 正在加载文档...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🧠 正在生成向量并构建数据库（首次运行会下载模型到本地缓存）...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;from_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;embedding&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;persist_directory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;collection_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;my_knowledge&quot;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 向量数据库已保存到 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;__name__&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;__main__&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;build_vector_db&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

运行：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;python build_vector_db.py
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  ⏳ 首次运行会自动下载 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BAAI/bge-small-zh-v1.5&lt;/code&gt; 模型（约 130MB）到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;~/.cache/huggingface/&lt;/code&gt;，&lt;strong&gt;之后完全离线可用&lt;/strong&gt;。

  ✅ 数据库文件将保存在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;./chroma_db/&lt;/code&gt;，&lt;strong&gt;仅在本地磁盘&lt;/strong&gt;。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第五步本地语义检索不依赖大模型直接返回相关段落&quot;&gt;🔍 第五步：本地语义检索（不依赖大模型，直接返回相关段落）&lt;/h2&gt;

创建文件：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;query.py&lt;/code&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# query.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_chroma&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.embeddings&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;BAAI/bge-small-zh-v1.5&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;device&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;cpu&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;normalize_embeddings&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;query_instruction&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;为这个句子生成表示以用于检索相关文章：&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;persist_directory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;embedding_function&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;collection_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;my_knowledge&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;search&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;query&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;k&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;similarity_search&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;query&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;k&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;k&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;🔍 问题：&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;query&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;doc&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;enumerate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;【结果 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;+&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;】（来源: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;doc&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;metadata&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;source&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;未知&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;）&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;doc&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;page_content&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[:&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;500&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;...&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;__name__&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;__main__&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;while&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;question&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;input&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;请输入你的问题（输入 &apos;quit&apos; 退出）：&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;question&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;lower&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;quit&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;break&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;search&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;question&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

运行：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;python query.py
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  ✅ 此时你可以直接提问，系统会返回最相关的原文片段，&lt;strong&gt;完全本地、无网络请求&lt;/strong&gt;。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第六步可选使用本地大模型生成答案rag&quot;&gt;🤖 第六步（可选）：使用本地大模型生成答案（RAG）&lt;/h2&gt;

&lt;h3 id=&quot;61-安装-ollamahttpsollamacom&quot;&gt;6.1 安装 Ollama（https://ollama.com/）&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;下载并安装 Ollama（支持 Windows/macOS/Linux）&lt;/li&gt;
  &lt;li&gt;安装后，&lt;strong&gt;默认只监听 localhost，不联网&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;62-拉取本地中文模型首次需要联网之后离线可用&quot;&gt;6.2 拉取本地中文模型（首次需要联网，之后离线可用）&lt;/h3&gt;
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ollama pull qwen:4b
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  模型大小约 2.5GB（4-bit 量化版），可在 16GB 内存笔记本 CPU 运行（稍慢）。
&lt;/blockquote&gt;

&lt;h3 id=&quot;63-创建-rag-查询脚本rag_querypy&quot;&gt;6.3 创建 RAG 查询脚本：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rag_query.py&lt;/code&gt;&lt;/h3&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# rag_query.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_chroma&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.embeddings&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_ollama&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;OllamaLLM&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_core.prompts&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ChatPromptTemplate&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_core.runnables&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunnablePassthrough&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_core.output_parsers&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;StrOutputParser&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# === 配置 ===
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;BAAI/bge-small-zh-v1.5&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;llm_model&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;qwen:4b&quot;&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# Ollama 中的模型名
&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# === 嵌入与向量库 ===
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;device&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;cpu&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;normalize_embeddings&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;query_instruction&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;为这个句子生成表示以用于检索相关文章：&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;persist_directory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;embedding_function&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;collection_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;my_knowledge&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;retriever&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;as_retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;search_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;k&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# === LLM 与 Prompt ===
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;llm&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;OllamaLLM&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;llm_model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;temperature&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;0.3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;template&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;
你是一个知识助手，请根据以下提供的上下文信息回答问题。
只使用上下文中的内容，不要编造。如果上下文没有相关信息，请回答“根据现有资料无法回答”。

上下文：
{context}

问题：{question}
答案：
&quot;&quot;&quot;&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ChatPromptTemplate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;from_template&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;template&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# === RAG 链 ===
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;rag_chain&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;context&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;question&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunnablePassthrough&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()}&lt;/span&gt;
    &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;
    &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;llm&lt;/span&gt;
    &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;StrOutputParser&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# === 查询 ===
&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;__name__&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;__main__&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;while&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;question&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;input&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;🧠 请输入你的问题（&apos;quit&apos; 退出）：&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;question&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;lower&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;quit&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;break&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;🤔 正在思考...&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;answer&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;rag_chain&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;invoke&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;question&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 答案：&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;answer&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  ⚠️ 确保 Ollama 正在运行（终端输入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ollama serve&lt;/code&gt;，或后台已启动）
&lt;/blockquote&gt;

运行：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;python rag_query.py
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  ✅ 此时系统会：
  &lt;ol&gt;
    &lt;li&gt;用本地嵌入模型检索相关段落&lt;/li&gt;
    &lt;li&gt;将段落 + 问题交给本地 Qwen 模型&lt;/li&gt;
    &lt;li&gt;生成自然语言答案
&lt;strong&gt;全程无任何数据上传到网络&lt;/strong&gt;&lt;/li&gt;
  &lt;/ol&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-隐私与安全说明&quot;&gt;🔒 隐私与安全说明&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;所有数据（原始文档、向量库、模型缓存）均保存在你的电脑。&lt;/li&gt;
  &lt;li&gt;ChromaDB 默认保存在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;./chroma_db/&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;Hugging Face 模型缓存路径：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;~/.cache/huggingface/hub/&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;Ollama 模型路径：
    &lt;ul&gt;
      &lt;li&gt;macOS: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;~/.ollama/models/&lt;/code&gt;&lt;/li&gt;
      &lt;li&gt;Windows: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;C:\Users\&amp;lt;user&amp;gt;\.ollama\models\&lt;/code&gt;&lt;/li&gt;
      &lt;li&gt;Linux: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;~/.ollama/models/&lt;/code&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;可将整个 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;local_knowledge_base&lt;/code&gt; 文件夹放入加密磁盘（如 VeraCrypt）进一步保护。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-附录完全离线使用提前下载模型&quot;&gt;📌 附录：完全离线使用（提前下载模型）&lt;/h2&gt;

如果你&lt;strong&gt;完全不能联网&lt;/strong&gt;，请在有网络的机器上提前下载：

&lt;h3 id=&quot;a-下载嵌入模型&quot;&gt;A. 下载嵌入模型&lt;/h3&gt;
&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;sentence_transformers&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SentenceTransformer&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;model&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SentenceTransformer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;BAAI/bge-small-zh-v1.5&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;save&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;./bge-small-zh&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# 保存到本地
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

然后修改代码中 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;model_name=&apos;./bge-small-zh&apos;&lt;/code&gt;

&lt;h3 id=&quot;b-下载-ollama-模型后复制到目标机器&quot;&gt;B. 下载 Ollama 模型后复制到目标机器&lt;/h3&gt;
Ollama 模型可直接复制 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;~/.ollama/models/&lt;/code&gt; 到另一台机器（需相同架构）。

&lt;hr /&gt;

&lt;h2 id=&quot;-总结&quot;&gt;✅ 总结&lt;/h2&gt;

你现在已经拥有一个：

&lt;ul&gt;
  &lt;li&gt;✅ &lt;strong&gt;100% 本地运行&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;支持中文&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;无需上传任何数据&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;可扩展（PDF/Word/笔记）&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;支持语义检索 + 智能问答&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

的私人知识库系统！

&lt;h1 id=&quot;需要图形界面以及自动监控文档更新&quot;&gt;需要图形界面以及自动监控文档更新&lt;/h1&gt;

在已有&lt;strong&gt;完全本地、离线、隐私安全&lt;/strong&gt;的知识库基础上，我们可以进一步：

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;添加图形界面（GUI）&lt;/strong&gt;：使用 Streamlit 快速搭建 Web 界面（仅本地访问）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;实现自动监控文档更新&lt;/strong&gt;：使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;watchdog&lt;/code&gt; 监听 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docs/&lt;/code&gt; 目录变化，自动增量更新向量库&lt;/li&gt;
&lt;/ol&gt;

&lt;blockquote&gt;
  ✅ 依然 &lt;strong&gt;不联网、不上传任何数据&lt;/strong&gt;，所有组件运行在本地。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-最终目标架构&quot;&gt;✅ 最终目标架构&lt;/h2&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;[docs/ 目录] ←─(watchdog 监控)─┐
                              ↓
[用户通过浏览器访问 http://localhost:8501]  
                              ↓  
[Streamlit GUI] → [检索/问答逻辑] → [ChromaDB + 本地 LLM]
                              ↑  
（文档变更时自动触发 rebuild 向量库）
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;第一步安装额外依赖&quot;&gt;第一步：安装额外依赖&lt;/h2&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;streamlit watchdog
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;第二步实现自动监控文档更新--增量更新向量库&quot;&gt;第二步：实现“自动监控文档更新 + 增量更新向量库”&lt;/h2&gt;

&lt;blockquote&gt;
  注意：ChromaDB 本身&lt;strong&gt;不支持高效增量删除&lt;/strong&gt;，但我们可以：
  &lt;ul&gt;
    &lt;li&gt;&lt;strong&gt;简单方案&lt;/strong&gt;：监控到变化 → 重新构建整个向量库（适合 &amp;lt;1000 文档）&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;进阶方案&lt;/strong&gt;：记录文档 hash，只更新变更/新增的 chunk（本文采用简单方案，清晰可靠）&lt;/li&gt;
  &lt;/ul&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;创建-auto_updaterpy&quot;&gt;创建 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;auto_updater.py&lt;/code&gt;&lt;/h3&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# auto_updater.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;os&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;time&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;hashlib&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;pathlib&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Path&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;watchdog.observers&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Observer&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;watchdog.events&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;FileSystemEventHandler&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;build_vector_db&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;build_vector_db&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# 复用之前写的构建函数
&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./docs&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;STATE_FILE&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./chroma_db/update_state.txt&quot;&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;compute_docs_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;计算 docs/ 目录下所有文件的 hash，用于判断是否变化&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;hash_md5&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;hashlib&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;md5&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;paths&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;sorted&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;rglob&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;*&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;path&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;paths&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;is_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;stat&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;stat&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;hash_md5&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;update&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;stat&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;st_mtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;encode&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;hash_md5&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;update&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;stat&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;st_size&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;encode&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;hash_md5&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;hexdigest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;load_last_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;exists&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;STATE_FILE&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;with&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;open&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;STATE_FILE&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;r&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;read&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;().&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;strip&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;save_current_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;current_hash&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;compute_docs_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;makedirs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;dirname&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;STATE_FILE&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;exist_ok&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;with&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;open&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;STATE_FILE&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;w&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;current_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;class&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;DocUpdateHandler&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;FileSystemEventHandler&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;__init__&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;callback&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;callback&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;callback&lt;/span&gt;
        &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;last_trigger&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;on_any_event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;# 防抖：5 秒内只触发一次
&lt;/span&gt;        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;last_trigger&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;5&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;src_path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;endswith&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;.txt&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;.md&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;.pdf&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)):&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;📁 检测到文档变更: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;src_path&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
                &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;last_trigger&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
                &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;callback&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;start_watcher&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;启动文件监控&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;observer&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Observer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;event_handler&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DocUpdateHandler&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;on_docs_changed&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;observer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;schedule&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;event_handler&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;recursive&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;observer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;start&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;👀 正在监控 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;abspath&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; 目录...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# 初始检查是否需要首次构建
&lt;/span&gt;    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;not&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;exists&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;./chroma_db/chroma.sqlite3&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# ChromaDB 默认文件
&lt;/span&gt;        &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🆕 首次运行：正在构建向量库...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;build_vector_db&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;save_current_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;current_hash&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;compute_docs_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;last_hash&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;load_last_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;current_hash&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;last_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🔄 检测到历史变更：正在重建向量库...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;build_vector_db&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;save_current_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;observer&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;on_docs_changed&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;文档变更时的回调&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;build_vector_db&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;save_current_hash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 向量库已更新！&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;第三步改造-build_vector_dbpy支持被调用&quot;&gt;第三步：改造 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;build_vector_db.py&lt;/code&gt;（支持被调用）&lt;/h2&gt;

修改 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;build_vector_db.py&lt;/code&gt;，使其可被其他模块调用而不重复初始化模型：

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# build_vector_db.py（修改版）
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_chroma&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.embeddings&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;ingest&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;os&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;shutil&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;BAAI/bge-small-zh-v1.5&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;device&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;cpu&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&apos;normalize_embeddings&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;query_instruction&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;为这个句子生成表示以用于检索相关文章：&quot;&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# 全局嵌入模型（避免重复加载）
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_EMBEDDING_MODEL&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;get_embedding_model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;global&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_EMBEDDING_MODEL&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_EMBEDDING_MODEL&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;is&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;_EMBEDDING_MODEL&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;HuggingFaceBgeEmbeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;model_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embedding_model_name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;encode_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;query_instruction&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;query_instruction&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_EMBEDDING_MODEL&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;build_vector_db&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;构建向量数据库（覆盖写入）&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;# 删除旧数据库（Chroma 不支持高效更新）
&lt;/span&gt;    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;exists&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;shutil&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;rmtree&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;makedirs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;get_embedding_model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🧠 正在生成向量...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;from_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;embedding&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;persist_directory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;collection_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;my_knowledge&quot;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 向量库重建完成&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;第四步创建图形界面streamlit&quot;&gt;第四步：创建图形界面（Streamlit）&lt;/h2&gt;

&lt;h3 id=&quot;创建-apppy&quot;&gt;创建 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app.py&lt;/code&gt;&lt;/h3&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# app.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;streamlit&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_chroma&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;build_vector_db&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;get_embedding_model&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_ollama&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;OllamaLLM&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_core.prompts&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ChatPromptTemplate&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_core.runnables&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunnablePassthrough&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_core.output_parsers&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;StrOutputParser&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;os&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# === 配置 ===
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;USE_RAG&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# 设为 False 则只返回检索结果
&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# === 初始化 ===
&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;@&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cache_resource&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;get_retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;get_embedding_model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Chroma&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;persist_directory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;embedding_function&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;embeddings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;collection_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;my_knowledge&quot;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;vectorstore&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;as_retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;search_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;k&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;

&lt;span class=&quot;o&quot;&gt;@&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cache_resource&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;get_rag_chain&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;retriever&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;get_retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;llm&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;OllamaLLM&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;qwen:4b&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;temperature&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;0.3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;template&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;
你是一个知识助手，请根据以下提供的上下文信息回答问题。
只使用上下文中的内容，不要编造。如果上下文没有相关信息，请回答“根据现有资料无法回答”。

上下文：
{context}

问题：{question}
答案：
&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ChatPromptTemplate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;from_template&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;template&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;context&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;question&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunnablePassthrough&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()}&lt;/span&gt;
        &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;
        &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;llm&lt;/span&gt;
        &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;StrOutputParser&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# === Streamlit UI ===
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;set_page_config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;page_title&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;我的本地知识库&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;layout&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;wide&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;title&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🧠 我的本地知识库（完全离线）&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# 输入框
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;query&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;text_input&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;请输入你的问题：&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;placeholder&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;例如：项目的关键时间节点是什么？&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;query&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;with&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;spinner&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;正在检索和思考...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;USE_RAG&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;try&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;answer&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;get_rag_chain&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;().&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;invoke&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;query&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;subheader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 答案&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;answer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;except&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;Exception&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;模型调用失败（请确认 Ollama 正在运行）：&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;USE_RAG&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# 回退到仅检索
&lt;/span&gt;        
        &lt;span class=&quot;c1&quot;&gt;# 显示检索到的原文（始终显示）
&lt;/span&gt;        &lt;span class=&quot;n&quot;&gt;retriever&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;get_retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;retriever&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;invoke&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;query&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;subheader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;📚 相关原文片段&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;doc&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;enumerate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;source&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;doc&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;metadata&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;source&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;未知&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;markdown&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;**来源 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;+&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;:** `&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;basename&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;source&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;`&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;text_area&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;doc&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;page_content&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;height&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;150&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;key&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;doc_&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# 侧边栏
&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;with&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sidebar&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;header&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;⚙️ 系统状态&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;db_exists&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;exists&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;join&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;chroma.sqlite3&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;success&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🟢 向量库已加载&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;db_exists&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;warning&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🔴 向量库未构建&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    
    &lt;span class=&quot;n&quot;&gt;ollama_status&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;🟢 Ollama 可用（若启用 RAG）&quot;&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;USE_RAG&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;⚪ 仅检索模式&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ollama_status&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    
    &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;info&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;📁 文档目录: `./docs`&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;info&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;🔒 所有数据仅保存在本地&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;第五步启动完整系统&quot;&gt;第五步：启动完整系统&lt;/h2&gt;

&lt;h3 id=&quot;创建启动脚本-startshlinuxmacos或-startbatwindows&quot;&gt;创建启动脚本 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.sh&lt;/code&gt;（Linux/macOS）或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.bat&lt;/code&gt;（Windows）&lt;/h3&gt;

&lt;h4 id=&quot;startsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.sh&lt;/code&gt;&lt;/h4&gt;
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;#!/bin/bash&lt;/span&gt;
&lt;span class=&quot;nb&quot;&gt;source &lt;/span&gt;venv/bin/activate

&lt;span class=&quot;c&quot;&gt;# 启动监控&lt;/span&gt;
python &lt;span class=&quot;nt&quot;&gt;-c&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;
from auto_updater import start_watcher
import time
observer = start_watcher()
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    observer.stop()
    observer.join()
&quot;&lt;/span&gt; &amp;amp;
&lt;span class=&quot;nv&quot;&gt;WATCHER_PID&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$!&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# 启动 Streamlit&lt;/span&gt;
streamlit run app.py &lt;span class=&quot;nt&quot;&gt;--server&lt;/span&gt;.port&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;8501 &lt;span class=&quot;nt&quot;&gt;--server&lt;/span&gt;.address&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;127.0.0.1

&lt;span class=&quot;c&quot;&gt;# 停止监控&lt;/span&gt;
&lt;span class=&quot;nb&quot;&gt;kill&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;$WATCHER_PID&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h4 id=&quot;windows-startbat&quot;&gt;Windows (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;start.bat&lt;/code&gt;)&lt;/h4&gt;
&lt;div class=&quot;language-bat highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;@echo &lt;span class=&quot;na&quot;&gt;off&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;call&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;venv&lt;/span&gt;\Scripts\activate

&lt;span class=&quot;nb&quot;&gt;start&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;/B &lt;/span&gt;&lt;span class=&quot;kd&quot;&gt;python&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;-c &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;from auto_updater import start_watcher; import time; o=start_watcher(); time.sleep(100000)&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;^
&lt;/span&gt;
&lt;span class=&quot;kd&quot;&gt;streamlit&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;run&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;app&lt;/span&gt;.py &lt;span class=&quot;na&quot;&gt;--server&lt;/span&gt;.port&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;m&quot;&gt;8501&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;--server&lt;/span&gt;.address&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;m&quot;&gt;127&lt;/span&gt;.0.0.1
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  💡 &lt;strong&gt;更简单的做法&lt;/strong&gt;：开两个终端分别运行：
  &lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# 终端 1：启动监控&lt;/span&gt;
python &lt;span class=&quot;nt&quot;&gt;-c&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;from auto_updater import start_watcher; start_watcher(); import time; time.sleep(100000)&quot;&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# 终端 2：启动 Web 界面&lt;/span&gt;
streamlit run app.py
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;  &lt;/div&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;第六步使用说明&quot;&gt;第六步：使用说明&lt;/h2&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;启动系统&lt;/strong&gt;：
    &lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;chmod&lt;/span&gt; +x start.sh  &lt;span class=&quot;c&quot;&gt;# Linux/macOS&lt;/span&gt;
./start.sh
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
    浏览器会自动打开 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;http://localhost:8501&lt;/code&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;添加/修改文档&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;直接编辑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;./docs/&lt;/code&gt; 下的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.md&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.txt&lt;/code&gt; 文件&lt;/li&gt;
      &lt;li&gt;保存后，&lt;strong&gt;5 秒内自动重建向量库&lt;/strong&gt;&lt;/li&gt;
      &lt;li&gt;刷新网页或重新提问即可看到新内容&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;隐私保障&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;Streamlit 默认只监听 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;127.0.0.1&lt;/code&gt;（仅本机访问）&lt;/li&gt;
      &lt;li&gt;无任何外网连接&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-可选增强&quot;&gt;🔧 可选增强&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;功能&lt;/th&gt;
      &lt;th&gt;实现方式&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;支持 PDF/Word&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt; 中启用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Unstructured&lt;/code&gt; 的 PDF/DOCX loader&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;显示文档修改时间&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;auto_updater.py&lt;/code&gt; 中记录变更日志&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;多用户（局域网）&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;修改 Streamlit 启动参数 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--server.address=0.0.0.0&lt;/code&gt;（⚠️ 仅限可信内网）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;加密存储&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;将整个项目目录放入 VeraCrypt 加密卷&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-总结-1&quot;&gt;✅ 总结&lt;/h2&gt;

你现在拥有一个：

&lt;ul&gt;
  &lt;li&gt;✅ &lt;strong&gt;图形化界面&lt;/strong&gt;（通过浏览器访问）&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;自动监控文档更新并重建知识库&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;支持检索 + 智能问答（RAG）&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;100% 本地运行，零数据上传&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;中文优化，隐私安全&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

的完整个人知识库系统！

&lt;blockquote&gt;
  💡 &lt;strong&gt;提示&lt;/strong&gt;：首次运行会较慢（下载模型 + 构建向量库），之后所有操作均在本地快速完成。
&lt;/blockquote&gt;

&lt;h1 id=&quot;在-ingestpy-中启用-unstructured-的-pdfdocx-loader&quot;&gt;在 ingest.py 中启用 Unstructured 的 PDF/DOCX loader&lt;/h1&gt;

要在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt; 中&lt;strong&gt;启用 Unstructured 的 PDF 和 DOCX（Word）文档加载功能&lt;/strong&gt;，你需要：

&lt;ol&gt;
  &lt;li&gt;安装额外的依赖（支持 PDF/DOCX 解析）&lt;/li&gt;
  &lt;li&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt; 中添加对应的加载器&lt;/li&gt;
  &lt;li&gt;确保 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Unstructured&lt;/code&gt; 使用本地模型（避免联网）&lt;/li&gt;
&lt;/ol&gt;

由于你要求&lt;strong&gt;完全本地、不上传任何信息到云端&lt;/strong&gt;，我们将配置 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Unstructured&lt;/code&gt; 使用 &lt;strong&gt;本地 OCR（如 Tesseract）&lt;/strong&gt; 和 &lt;strong&gt;本地解析器&lt;/strong&gt;，禁用其默认可能调用的远程 API（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;unstructured-api&lt;/code&gt;）。

&lt;hr /&gt;

&lt;h2 id=&quot;-第一步安装必要的本地依赖&quot;&gt;✅ 第一步：安装必要的本地依赖&lt;/h2&gt;

&lt;h3 id=&quot;11-安装-python-依赖&quot;&gt;1.1 安装 Python 依赖&lt;/h3&gt;
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# 已有基础&lt;/span&gt;
pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;unstructured[local-inference]

&lt;span class=&quot;c&quot;&gt;# 新增：PDF 和 DOCX 支持&lt;/span&gt;
pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;unstructured[pdf]      &lt;span class=&quot;c&quot;&gt;# 包含 pdf2image, PyPDF2&lt;/span&gt;
pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;unstructured[docx]     &lt;span class=&quot;c&quot;&gt;# 包含 python-docx&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# 可选但推荐（提高 PDF 表格/图文解析质量）&lt;/span&gt;
pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;pymupdf          &lt;span class=&quot;c&quot;&gt;# 更快的 PDF 解析（替代 pdf2image）&lt;/span&gt;
pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;poppler-utils     &lt;span class=&quot;c&quot;&gt;# 用于 pdf2image（需系统安装）&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  ⚠️ 注意：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;unstructured[pdf]&lt;/code&gt; 默认会尝试使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pdf2image&lt;/code&gt;，它依赖系统级的 &lt;strong&gt;Poppler&lt;/strong&gt;。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h3 id=&quot;12-安装系统级依赖windows&quot;&gt;1.2 安装系统级依赖（Windows）&lt;/h3&gt;

&lt;h4 id=&quot;1安装-tesseract-ocr用于-pdf-中扫描图像的文字识别&quot;&gt;（1）安装 &lt;strong&gt;Tesseract OCR&lt;/strong&gt;（用于 PDF 中扫描图像的文字识别）&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;下载地址：https://github.com/UB-Mannheim/tesseract/wiki&lt;/li&gt;
  &lt;li&gt;安装时勾选 &lt;strong&gt;“Additional language data (e.g. Chinese)”&lt;/strong&gt; → 选择 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chi_sim&lt;/code&gt;（简体中文）和 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chi_tra&lt;/code&gt;（繁体）&lt;/li&gt;
  &lt;li&gt;安装完成后，将 Tesseract 路径（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;C:\Program Files\Tesseract-OCR&lt;/code&gt;）加入系统 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PATH&lt;/code&gt; 环境变量&lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;2安装-poppler用于-pdf2image&quot;&gt;（2）安装 &lt;strong&gt;Poppler&lt;/strong&gt;（用于 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pdf2image&lt;/code&gt;）&lt;/h4&gt;
&lt;ul&gt;
  &lt;li&gt;下载预编译版：https://github.com/oschwartz10612/poppler-windows/releases/&lt;/li&gt;
  &lt;li&gt;解压到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;C:\poppler&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;将 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;C:\poppler\Library\bin&lt;/code&gt; 加入系统 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PATH&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
  ✅ 验证安装：
  &lt;pre&gt;&lt;code class=&quot;language-cmd&quot;&gt;tesseract --version
pdftoppm -h
&lt;/code&gt;&lt;/pre&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第二步修改-ingestpy-启用-pdfdocx-加载器&quot;&gt;✅ 第二步：修改 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt; 启用 PDF/DOCX 加载器&lt;/h2&gt;

更新你的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt; 文件如下（关键：&lt;strong&gt;禁用远程 API，强制本地解析&lt;/strong&gt;）：

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# ingest.py （更新版：支持 PDF / DOCX / TXT / MD，完全本地）
&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;os&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.document_loaders&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;DirectoryLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;TextLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;UnstructuredMarkdownLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_community.document_loaders.unstructured&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;UnstructuredFileLoader&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;typing&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;List&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;warnings&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;warnings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;filterwarnings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;ignore&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;category&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;UserWarning&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;module&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;unstructured&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./docs&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;./chroma_db&quot;&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;List&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;加载所有支持的文档（TXT, MD, PDF, DOCX），完全本地解析&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# === .txt 文件 ===
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;txt_loader&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DirectoryLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;glob&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;*.txt&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;loader_cls&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TextLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;loader_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;encoding&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;utf-8&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;extend&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;txt_loader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;load&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# === .md 文件 ===
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;md_loader&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DirectoryLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;glob&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;*.md&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;loader_cls&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;UnstructuredMarkdownLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;loader_kwargs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;encoding&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;utf-8&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;extend&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;md_loader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;load&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# === .pdf 文件 ===
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;pdf_files&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;glob&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;*.pdf&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)]&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;pdf_file&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;pdf_files&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;📄 正在解析 PDF: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;basename&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;pdf_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;loader&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;UnstructuredFileLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;pdf_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;mode&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;single&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# 或 &quot;elements&quot;（更细粒度）
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;strategy&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;fast&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# &quot;hi_res&quot; 更准但慢，需 OCR
&lt;/span&gt;            &lt;span class=&quot;c1&quot;&gt;# 关键：强制本地，不调用 API
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;api_url&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;   &lt;span class=&quot;c1&quot;&gt;# 禁用远程 API
&lt;/span&gt;            &lt;span class=&quot;c1&quot;&gt;# 启用本地 OCR（如果 PDF 是扫描件）
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;ocr_languages&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;chi_sim&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;eng&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# 中英混合
&lt;/span&gt;        &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;extend&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;loader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;load&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# === .docx 文件 ===
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;docx_files&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DOCS_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;glob&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;*.docx&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)]&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;docx_file&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;docx_files&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;📝 正在解析 DOCX: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;basename&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;docx_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;loader&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;UnstructuredFileLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;docx_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;mode&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;single&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;strategy&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;fast&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;api_url&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# 禁用远程 API
&lt;/span&gt;        &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;extend&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;loader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;load&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 共加载 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; 个文档片段&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# --- 保留原有的 split_documents 函数 ---
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;langchain_text_splitters&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RecursiveCharacterTextSplitter&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;pathlib&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Path&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;text_splitter&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RecursiveCharacterTextSplitter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;chunk_size&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;500&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;chunk_overlap&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;50&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;length_function&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;is_separator_regex&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;text_splitter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 切分为 &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; 个文本块&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;__name__&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;__main__&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;load_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;split_documents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;docs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;makedirs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;exist_ok&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;with&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;open&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;join&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;PERSIST_DIR&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;chunks.txt&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;w&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;encoding&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;utf-8&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;chunk&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;enumerate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;--- Chunk &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;i&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; ---&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;chunk&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;page_content&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;✅ 文本块已保存（供调试）&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第三步验证配置确保无网络请求&quot;&gt;✅ 第三步：验证配置（确保无网络请求）&lt;/h2&gt;

&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UnstructuredFileLoader&lt;/code&gt; 默认在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;api_url=None&lt;/code&gt; 时会使用 &lt;strong&gt;本地解析&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;partition&lt;/code&gt; 函数），不会连接任何远程服务。

你可以通过以下方式确认：
&lt;ul&gt;
  &lt;li&gt;禁用网络（拔网线 / 关 WiFi）&lt;/li&gt;
  &lt;li&gt;运行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;python ingest.py&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;如果能正常解析 PDF/DOCX → 说明完全本地&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
  🔒 安全提示：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Unstructured&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UnstructuredAPIFileLoader&lt;/code&gt; 才会联网，我们用的是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UnstructuredFileLoader&lt;/code&gt;（本地版）。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-第四步可选提高-pdf-解析质量&quot;&gt;✅ 第四步（可选）：提高 PDF 解析质量&lt;/h2&gt;

如果你的 PDF 是&lt;strong&gt;扫描件（图片型）&lt;/strong&gt;，确保 Tesseract 已正确安装并支持中文：

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# 在 UnstructuredFileLoader 中显式指定 OCR 选项
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;loader&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;UnstructuredFileLoader&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;pdf_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;strategy&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;hi_res&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;          &lt;span class=&quot;c1&quot;&gt;# 启用高级布局分析
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;ocr_languages&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;chi_sim+eng&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;# 中英混合
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;include_page_breaks&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;api_url&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote&gt;
  💡 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;strategy=&quot;hi_res&quot;&lt;/code&gt; 会调用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;layoutparser&lt;/code&gt; 和 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Tesseract&lt;/code&gt;，需要额外安装：
  &lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;unstructured[local-inference]
&lt;span class=&quot;c&quot;&gt;# 已包含 layoutparser, detectron2（但 detectron2 在 Windows 安装复杂）&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;  &lt;/div&gt;
  如果安装失败，可降级使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;strategy=&quot;ocr_only&quot;&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;fast&quot;&lt;/code&gt;。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-文件目录示例&quot;&gt;✅ 文件目录示例&lt;/h2&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;local_knowledge_base/
└── docs/
    ├── notes.md
    ├── summary.txt
    ├── report.pdf        ← 支持！
    └── meeting.docx      ← 支持！
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

放入这些文件后，运行：
&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;python ingest.py
python build_vector_db.py
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
即可将 PDF/DOCX 内容纳入知识库。

&lt;hr /&gt;

&lt;h2 id=&quot;️-常见问题解决&quot;&gt;⚠️ 常见问题解决&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;问题&lt;/th&gt;
      &lt;th&gt;解决方案&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TesseractNotFoundError&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;安装 Tesseract 并加入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PATH&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;poppler not installed&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;安装 Poppler 并加入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PATH&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;中文 OCR 识别乱码&lt;/td&gt;
      &lt;td&gt;安装 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chi_sim&lt;/code&gt; 语言包（Tesseract 安装时勾选）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;DOCX 表格丢失&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;unstructured&lt;/code&gt; 对复杂表格支持有限，可考虑转为 PDF 或 Markdown 预处理&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-总结-2&quot;&gt;✅ 总结&lt;/h2&gt;

你现在已经成功在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ingest.py&lt;/code&gt; 中启用了：

&lt;ul&gt;
  &lt;li&gt;✅ &lt;strong&gt;PDF 解析&lt;/strong&gt;（文本型 + 扫描型 OCR）&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;DOCX 解析&lt;/strong&gt;（文字、标题、列表）&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;完全本地运行&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;✅ &lt;strong&gt;不上传任何数据到云端&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

所有文档（包括 PDF/DOCX）都会被切块、向量化，并纳入你的本地知识库，可通过图形界面查询。
</description>
        <pubDate>Wed, 07 Jan 2026 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2026/01/07/make_local_knowledge_base/</link>
        <guid isPermaLink="true">https://titron.github.io/2026/01/07/make_local_knowledge_base/</guid>
        
        <category>knowledge</category>
        
        <category>base</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>Interleaved, planar, or semi-planar,都是什么意思</title>
        <description>&lt;ul id=&quot;markdown-toc&quot;&gt;
  &lt;li&gt;&lt;a href=&quot;#-核心概念yuv-三通道&quot; id=&quot;markdown-toc--核心概念yuv-三通道&quot;&gt;🎯 核心概念：YUV 三通道&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#1--planar-平面格式&quot; id=&quot;markdown-toc-1--planar-平面格式&quot;&gt;1. ✅ **Planar **(平面格式)&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#定义&quot; id=&quot;markdown-toc-定义&quot;&gt;定义：&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#内存布局yuv420-示例44-图像&quot; id=&quot;markdown-toc-内存布局yuv420-示例44-图像&quot;&gt;内存布局（YUV420 示例，4×4 图像）：&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#特点&quot; id=&quot;markdown-toc-特点&quot;&gt;特点：&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#2--interleaved-交错格式&quot; id=&quot;markdown-toc-2--interleaved-交错格式&quot;&gt;2. ✅ **Interleaved **(交错格式)&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#定义-1&quot; id=&quot;markdown-toc-定义-1&quot;&gt;定义：&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#rgb-交错示例每个像素-r-g-b-连续&quot; id=&quot;markdown-toc-rgb-交错示例每个像素-r-g-b-连续&quot;&gt;RGB 交错示例（每个像素 R-G-B 连续）：&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#yuv-交错如-yuyv&quot; id=&quot;markdown-toc-yuv-交错如-yuyv&quot;&gt;YUV 交错（如 YUYV）：&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#特点-1&quot; id=&quot;markdown-toc-特点-1&quot;&gt;特点：&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#3--semi-planar-半平面格式&quot; id=&quot;markdown-toc-3--semi-planar-半平面格式&quot;&gt;3. ✅ **Semi-planar **(半平面格式)&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#定义-2&quot; id=&quot;markdown-toc-定义-2&quot;&gt;定义：&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#内存布局yuv420-semi-planar&quot; id=&quot;markdown-toc-内存布局yuv420-semi-planar&quot;&gt;内存布局（YUV420 Semi-planar）：&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#特点-2&quot; id=&quot;markdown-toc-特点-2&quot;&gt;特点：&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-三种格式对比以-yuv420-为例&quot; id=&quot;markdown-toc--三种格式对比以-yuv420-为例&quot;&gt;📊 三种格式对比（以 YUV420 为例）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-实际应用场景&quot; id=&quot;markdown-toc--实际应用场景&quot;&gt;🔧 实际应用场景&lt;/a&gt;    &lt;ul&gt;
      &lt;li&gt;&lt;a href=&quot;#1-android-app-开发&quot; id=&quot;markdown-toc-1-android-app-开发&quot;&gt;1. &lt;strong&gt;Android App 开发&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#2-视频解码ffmpeg--gpu&quot; id=&quot;markdown-toc-2-视频解码ffmpeg--gpu&quot;&gt;2. &lt;strong&gt;视频解码（FFmpeg + GPU）&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
      &lt;li&gt;&lt;a href=&quot;#3-嵌入式-dsp-图像处理&quot; id=&quot;markdown-toc-3-嵌入式-dsp-图像处理&quot;&gt;3. &lt;strong&gt;嵌入式 DSP 图像处理&lt;/strong&gt;&lt;/a&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#-总结&quot; id=&quot;markdown-toc--总结&quot;&gt;✅ 总结&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

在图像处理、视频编码和内存存储中，&lt;strong&gt;Interleaved&lt;/strong&gt;（交错）、&lt;strong&gt;Planar&lt;/strong&gt;（平面）和 &lt;strong&gt;Semi-planar&lt;/strong&gt;（半平面）是描述&lt;strong&gt;多通道数据&lt;/strong&gt;（如 RGB、YUV）在内存中&lt;strong&gt;布局方式&lt;/strong&gt;的三种常见格式。它们直接影响&lt;strong&gt;内存访问效率、硬件解码兼容性、图像处理性能&lt;/strong&gt;。

下面以最常见的 &lt;strong&gt;YUV 色彩空间&lt;/strong&gt;（视频常用）为例进行说明（RGB 原理类似）：

&lt;hr /&gt;

&lt;h2 id=&quot;-核心概念yuv-三通道&quot;&gt;🎯 核心概念：YUV 三通道&lt;/h2&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Y&lt;/strong&gt;：亮度（Luma），人眼对亮度最敏感&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;U、V&lt;/strong&gt;：色度（Chroma），可压缩而不明显影响观感&lt;/li&gt;
  &lt;li&gt;常见采样格式：&lt;strong&gt;YUV420&lt;/strong&gt;（U/V 分辨率是 Y 的 1/2）&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;1--planar-平面格式&quot;&gt;1. ✅ **Planar **(平面格式)&lt;/h2&gt;

&lt;h3 id=&quot;定义&quot;&gt;定义：&lt;/h3&gt;
所有 &lt;strong&gt;Y 像素连续存储&lt;/strong&gt;，然后 &lt;strong&gt;所有 U 像素连续存储&lt;/strong&gt;，最后 &lt;strong&gt;所有 V 像素连续存储&lt;/strong&gt;。

&lt;h3 id=&quot;内存布局yuv420-示例44-图像&quot;&gt;内存布局（YUV420 示例，4×4 图像）：&lt;/h3&gt;
&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;内存地址 → [YYYY YYYY YYYY YYYY UU UU VV VV]
           ↑     ↑     ↑     ↑   ↑   ↑
          Y平面  |     |     |  U平面 V平面
                全部Y数据    全部U数据 全部V数据
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;特点&quot;&gt;特点：&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;优点&lt;/strong&gt;：通道分离，便于单独处理 Y/U/V（如只增强亮度）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;缺点&lt;/strong&gt;：访问一个像素需跨多个内存区域，&lt;strong&gt;缓存不友好&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;常见格式&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;I420&lt;/code&gt;（YUV420 Planar）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;YV12&lt;/code&gt;（Y, V, U 顺序，Planar）&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
  📌 &lt;strong&gt;典型应用&lt;/strong&gt;：FFmpeg、OpenCV（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cv::COLOR_YUV2BGR_I420&lt;/code&gt;）、部分摄像头原始输出。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;2--interleaved-交错格式&quot;&gt;2. ✅ **Interleaved **(交错格式)&lt;/h2&gt;

&lt;h3 id=&quot;定义-1&quot;&gt;定义：&lt;/h3&gt;
&lt;strong&gt;Y、U、V 像素按像素或宏块交错存储&lt;/strong&gt;。常见于 &lt;strong&gt;RGB&lt;/strong&gt;，YUV 中较少（但有）。

&lt;h3 id=&quot;rgb-交错示例每个像素-r-g-b-连续&quot;&gt;RGB 交错示例（每个像素 R-G-B 连续）：&lt;/h3&gt;
&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;[R0 G0 B0] [R1 G1 B1] [R2 G2 B2] ...
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;yuv-交错如-yuyv&quot;&gt;YUV 交错（如 YUYV）：&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;每 2 个 Y 共享 1 组 U、V（YUV422）：
    &lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;[Y0 U0 Y1 V0] [Y2 U1 Y3 V1] ...
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;特点-1&quot;&gt;特点：&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;优点&lt;/strong&gt;：单像素数据连续，&lt;strong&gt;缓存友好&lt;/strong&gt;，适合逐像素处理。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;缺点&lt;/strong&gt;：Y/U/V 无法独立访问。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;常见格式&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RGB24&lt;/code&gt;（R-G-B 交错）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;YUYV&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UYVY&lt;/code&gt;（YUV422 Interleaved）&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
  📌 &lt;strong&gt;典型应用&lt;/strong&gt;：显示器帧缓冲、USB 摄像头（UVC）、DirectShow。
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;3--semi-planar-半平面格式&quot;&gt;3. ✅ **Semi-planar **(半平面格式)&lt;/h2&gt;

&lt;h3 id=&quot;定义-2&quot;&gt;定义：&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Y 平面连续存储&lt;/strong&gt;（同 Planar）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;U 和 V 交错存储&lt;/strong&gt;（如 UVUVUV…）&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;内存布局yuv420-semi-planar&quot;&gt;内存布局（YUV420 Semi-planar）：&lt;/h3&gt;
&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;[YYYY YYYY YYYY YYYY UV UV UV UV]
 ↑     ↑     ↑     ↑   ↑
Y平面（全部Y）        UV平面（U和V交替）
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;特点-2&quot;&gt;特点：&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;优点&lt;/strong&gt;：Y 单独存储（便于亮度处理），UV 合并（减少内存碎片），&lt;strong&gt;硬件友好&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;缺点&lt;/strong&gt;：U/V 仍需解交错。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;常见格式&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV12&lt;/code&gt;：Y + UV 交错（U 在前）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV21&lt;/code&gt;：Y + VU 交错（V 在前，Android camera 默认）&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
  📌 &lt;strong&gt;典型应用&lt;/strong&gt;：
  &lt;ul&gt;
    &lt;li&gt;&lt;strong&gt;Android Camera&lt;/strong&gt; 输出格式：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV21&lt;/code&gt;&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Intel/AMD/NVIDIA GPU&lt;/strong&gt; 视频解码器：默认输出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV12&lt;/code&gt;&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;H.264/H.265 解码&lt;/strong&gt;：硬件解码器常输出 Semi-planar&lt;/li&gt;
  &lt;/ul&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-三种格式对比以-yuv420-为例&quot;&gt;📊 三种格式对比（以 YUV420 为例）&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;特性&lt;/th&gt;
      &lt;th&gt;Planar (I420)&lt;/th&gt;
      &lt;th&gt;Semi-planar (NV12)&lt;/th&gt;
      &lt;th&gt;Interleaved (YUYV)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Y 存储&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;连续&lt;/td&gt;
      &lt;td&gt;连续&lt;/td&gt;
      &lt;td&gt;与 U/V 交错&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;U/V 存储&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;U 连续，V 连续&lt;/td&gt;
      &lt;td&gt;UV 交替（UVUV…）&lt;/td&gt;
      &lt;td&gt;与 Y 交错&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;内存块数&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;3 块（Y, U, V）&lt;/td&gt;
      &lt;td&gt;2 块（Y, UV）&lt;/td&gt;
      &lt;td&gt;1 块&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;硬件支持&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;一般&lt;/td&gt;
      &lt;td&gt;⭐⭐⭐（GPU/编解码器首选）&lt;/td&gt;
      &lt;td&gt;中等&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Android Camera&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
      &lt;td&gt;✅ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV21&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;OpenCV 支持&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;✅ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;I420&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV12&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;YUYV&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-实际应用场景&quot;&gt;🔧 实际应用场景&lt;/h2&gt;

&lt;h3 id=&quot;1-android-app-开发&quot;&gt;1. &lt;strong&gt;Android App 开发&lt;/strong&gt;&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;相机预览回调格式是 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV21&lt;/code&gt;&lt;/strong&gt;（Semi-planar）&lt;/li&gt;
  &lt;li&gt;若需用 OpenCV 处理，需转换：
    &lt;div class=&quot;language-java highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;// Java (Android)&lt;/span&gt;
&lt;span class=&quot;nc&quot;&gt;Mat&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;yuvMat&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;Mat&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;height&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;height&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;/&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;CvType&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;CV_8UC1&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;);&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;yuvMat&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;put&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nv21ByteArray&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;);&lt;/span&gt;
&lt;span class=&quot;nc&quot;&gt;Mat&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bgrMat&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;Mat&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;();&lt;/span&gt;
&lt;span class=&quot;nc&quot;&gt;Imgproc&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;cvtColor&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;yuvMat&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bgrMat&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;Imgproc&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;COLOR_YUV2BGR_NV21&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;2-视频解码ffmpeg--gpu&quot;&gt;2. &lt;strong&gt;视频解码（FFmpeg + GPU）&lt;/strong&gt;&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;硬件解码器（如 VAAPI、CUDA）输出 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NV12&lt;/code&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;渲染到屏幕前可能需转为 RGB Interleaved&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;3-嵌入式-dsp-图像处理&quot;&gt;3. &lt;strong&gt;嵌入式 DSP 图像处理&lt;/strong&gt;&lt;/h3&gt;
&lt;ul&gt;
  &lt;li&gt;为节省带宽，ISP 输出 &lt;strong&gt;Planar YUV&lt;/strong&gt;（Y 单独处理降噪，UV 降分辨率）&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;-总结&quot;&gt;✅ 总结&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;格式&lt;/th&gt;
      &lt;th&gt;中文&lt;/th&gt;
      &lt;th&gt;存储方式&lt;/th&gt;
      &lt;th&gt;典型用途&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Planar&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;平面格式&lt;/td&gt;
      &lt;td&gt;Y / U / V 分三个连续区域&lt;/td&gt;
      &lt;td&gt;软件处理、FFmpeg&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Semi-planar&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;半平面格式&lt;/td&gt;
      &lt;td&gt;Y 连续 + UV 交错&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Android、GPU、硬件编解码&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Interleaved&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;交错格式&lt;/td&gt;
      &lt;td&gt;每像素/宏块内 YUV 交错&lt;/td&gt;
      &lt;td&gt;显示器、RGB 图像、摄像头&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;blockquote&gt;
  💡 &lt;strong&gt;记住&lt;/strong&gt;：
  &lt;ul&gt;
    &lt;li&gt;&lt;strong&gt;Planar = 三通道分离&lt;/strong&gt;&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Semi-planar = Y 分离，UV 合并交错&lt;/strong&gt;&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Interleaved = 所有通道混合交错&lt;/strong&gt;&lt;/li&gt;
  &lt;/ul&gt;
&lt;/blockquote&gt;

理解这三种布局，对&lt;strong&gt;优化图像处理性能、调试视频 pipeline、跨平台数据转换&lt;/strong&gt;至关重要。
</description>
        <pubDate>Fri, 26 Dec 2025 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2025/12/26/memoryStorageFormats_isp_vsp/</link>
        <guid isPermaLink="true">https://titron.github.io/2025/12/26/memoryStorageFormats_isp_vsp/</guid>
        
        <category>vsp,</category>
        
        <category>isp</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>Video Signal Process technology lists</title>
        <description>&lt;ul id=&quot;markdown-toc&quot;&gt;
  &lt;li&gt;&lt;a href=&quot;#1-anti-aliasing-filter&quot; id=&quot;markdown-toc-1-anti-aliasing-filter&quot;&gt;1. Anti-Aliasing Filter&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#2-black-level-compensation&quot; id=&quot;markdown-toc-2-black-level-compensation&quot;&gt;2. Black Level Compensation&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#3-chroma--luma-noise-filters色度与亮度噪声滤波器&quot; id=&quot;markdown-toc-3-chroma--luma-noise-filters色度与亮度噪声滤波器&quot;&gt;3. Chroma &amp;amp; Luma Noise Filters(色度与亮度噪声滤波器)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#4-chromatic-aberration色差&quot; id=&quot;markdown-toc-4-chromatic-aberration色差&quot;&gt;4. Chromatic Aberration(色差)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#5-color-correction-blendingfoganti-foginverse-gamma-correction&quot; id=&quot;markdown-toc-5-color-correction-blendingfoganti-foginverse-gamma-correction&quot;&gt;5. Color Correction-blending/fog/anti-fog/inverse Gamma correction&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#6-color-space-conversion&quot; id=&quot;markdown-toc-6-color-space-conversion&quot;&gt;6. Color Space Conversion&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#7-brightness-control&quot; id=&quot;markdown-toc-7-brightness-control&quot;&gt;7. Brightness Control&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#8-contrast-control&quot; id=&quot;markdown-toc-8-contrast-control&quot;&gt;8. Contrast Control&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#9-defect-pixel-correction&quot; id=&quot;markdown-toc-9-defect-pixel-correction&quot;&gt;9. Defect Pixel Correction&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#10-digital-gain-control&quot; id=&quot;markdown-toc-10-digital-gain-control&quot;&gt;10. Digital Gain Control&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#11-edge-enhancement-sharpening&quot; id=&quot;markdown-toc-11-edge-enhancement-sharpening&quot;&gt;11. Edge Enhancement-Sharpening&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#12-gamma-correction&quot; id=&quot;markdown-toc-12-gamma-correction&quot;&gt;12. Gamma Correction&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#13-hue-saturation-control色调饱和度控制&quot; id=&quot;markdown-toc-13-hue-saturation-control色调饱和度控制&quot;&gt;13. Hue Saturation Control(色调饱和度控制)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#14-white-balance&quot; id=&quot;markdown-toc-14-white-balance&quot;&gt;14. White Balance&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

Video Signal Process technology lists：

&lt;h3 id=&quot;1-anti-aliasing-filter&quot;&gt;1. Anti-Aliasing Filter&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_Anti-AliasingFilter.png&quot; alt=&quot;Anti-Aliasing Filter&quot; /&gt;
&lt;h3 id=&quot;2-black-level-compensation&quot;&gt;2. Black Level Compensation&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_BlackLevelCompensation.png&quot; alt=&quot;Black Level Compensation&quot; /&gt;
&lt;h3 id=&quot;3-chroma--luma-noise-filters色度与亮度噪声滤波器&quot;&gt;3. Chroma &amp;amp; Luma Noise Filters(色度与亮度噪声滤波器)&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_Chroma_LumaNoiseFilters.png&quot; alt=&quot;Chroma &amp;amp; Luma Noise Filters&quot; /&gt;
&lt;h3 id=&quot;4-chromatic-aberration色差&quot;&gt;4. Chromatic Aberration(色差)&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_ChromaticAberration.png&quot; alt=&quot;Chromatic Aberration&quot; /&gt;
&lt;h3 id=&quot;5-color-correction-blendingfoganti-foginverse-gamma-correction&quot;&gt;5. Color Correction-blending/fog/anti-fog/inverse Gamma correction&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_ColorCorrection.png&quot; alt=&quot;Color Correction-blending&quot; /&gt;
&lt;h3 id=&quot;6-color-space-conversion&quot;&gt;6. Color Space Conversion&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_ColorSpaceConversion.png&quot; alt=&quot;Color Space Conversion&quot; /&gt;
&lt;h3 id=&quot;7-brightness-control&quot;&gt;7. Brightness Control&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_BrightnessControl.png&quot; alt=&quot;Brightness Control&quot; /&gt;
&lt;h3 id=&quot;8-contrast-control&quot;&gt;8. Contrast Control&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_ContrastControl.png&quot; alt=&quot;Contrast Control&quot; /&gt;
&lt;h3 id=&quot;9-defect-pixel-correction&quot;&gt;9. Defect Pixel Correction&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_DefectPixelCorrection.png&quot; alt=&quot;Defect Pixel Correction&quot; /&gt;
&lt;h3 id=&quot;10-digital-gain-control&quot;&gt;10. Digital Gain Control&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_DigitalGainControl.png&quot; alt=&quot;Digital Gain Control&quot; /&gt;
&lt;h3 id=&quot;11-edge-enhancement-sharpening&quot;&gt;11. Edge Enhancement-Sharpening&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_sharpening.png&quot; alt=&quot;sharpening&quot; /&gt;
&lt;h3 id=&quot;12-gamma-correction&quot;&gt;12. Gamma Correction&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_GammaCorrection.png&quot; alt=&quot;Gamma Correction&quot; /&gt;
&lt;h3 id=&quot;13-hue-saturation-control色调饱和度控制&quot;&gt;13. Hue Saturation Control(色调饱和度控制)&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_HueSaturation.png&quot; alt=&quot;Hue Saturation Control&quot; /&gt;
&lt;h3 id=&quot;14-white-balance&quot;&gt;14. White Balance&lt;/h3&gt;
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-12-24-vsp_whiteBalance.png&quot; alt=&quot;White Balance&quot; /&gt;

</description>
        <pubDate>Wed, 24 Dec 2025 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2025/12/24/imageprocess/</link>
        <guid isPermaLink="true">https://titron.github.io/2025/12/24/imageprocess/</guid>
        
        <category>vsp,</category>
        
        <category>video</category>
        
        <category>signal</category>
        
        <category>process</category>
        
        
        <category>experience</category>
        
      </item>
    
      <item>
        <title>audio系统中，WAV和PCM的关系和区别</title>
        <description>&lt;ul id=&quot;markdown-toc&quot;&gt;
  &lt;li&gt;&lt;a href=&quot;#wav文件格式&quot; id=&quot;markdown-toc-wav文件格式&quot;&gt;wav文件格式&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#将录音写成wav格式的文件&quot; id=&quot;markdown-toc-将录音写成wav格式的文件&quot;&gt;将录音写成wav格式的文件&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#wav转pcm&quot; id=&quot;markdown-toc-wav转pcm&quot;&gt;wav转pcm&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#pcm转wav&quot; id=&quot;markdown-toc-pcm转wav&quot;&gt;pcm转wav&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;
&lt;a href=&quot;https://zhuanlan.zhihu.com/p/518831885&quot;&gt;WAV和PCM的关系和区别&lt;/a&gt;

wav是一种无损的音频文件格式，WAV符合 PIFF(Resource Interchange File Format)规范。
所有的WAV都有一个文件头，这个文件头音频流的编码参数。
WAV对音频流的编码没有硬性规定，除了PCM之外，还有几乎所有支持ACM规范的编码都可以为WAV的音频流进行编码。
缺点：体积十分大！

PCM（Pulse Code Modulation—-脉码调制录音)。
所谓PCM录音就是将声音等模拟信号变成符号化的脉冲列，再予以记录。
PCM信号是由“1”、“0”等符号构成的数字信号，而&lt;em&gt;未经过任何编码和压缩处理&lt;/em&gt;。
与模拟信号比，它不易受传送系统的杂波及失真的影响。动态范围宽，可得到音质相当好的影响效果。

&lt;em&gt;简单来说：wav是一种无损的音频文件格式，pcm是没有压缩的编码方式。&lt;/em&gt;

WAV可以使用多种音频编码来压缩其音频流，不过我们常见的都是音频流被PCM编码处理的WAV，但这不表示WAV只能使用PCM编码，MP3编码同样也可以运用在WAV中。
基于PCM编码的WAV被作为了一种中介的格式，常常使用在其他编码的相互转换之中，例如MP3转换成WMA。

&lt;em&gt;简单来说：pcm是无损wav文件中音频数据的一种编码方式，但wav还可以用其它方式编码。&lt;/em&gt;
&lt;h2 id=&quot;wav文件格式&quot;&gt;wav文件格式&lt;/h2&gt;
在文件的前44字节放置标头(header)，使播放器或编辑器能够简单掌握文件的基本信息，其内容以区块(chunk)为最小单位，每一区块长度为4字节。
&lt;img src=&quot;https://github.com/titron/titron.github.io/raw/master/img/2025-11-13-wav_pcm_wav_header.jpg&quot; alt=&quot;wav header&quot; /&gt;

&lt;h2 id=&quot;将录音写成wav格式的文件&quot;&gt;将录音写成wav格式的文件&lt;/h2&gt;
&lt;div class=&quot;language-c highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;// 将录音文件保存为wav格式，这需要手动填充wav的文件头信息&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;private&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RandomAccessFile&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;fopen&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;String&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;throws&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;IOException&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;File&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;File&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;exists&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;delete&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;File&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;parentDir&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;getParentFile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;!&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;parentDir&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;exists&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;parentDir&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mkdirs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;RandomAccessFile&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;RandomAccessFile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;rw&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;// 16K、16bit、单声道&lt;/span&gt;
    &lt;span class=&quot;cm&quot;&gt;/* RIFF header */&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;RIFF&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// riff id&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeInt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// riff chunk size *PLACEHOLDER*&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;WAVE&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// wave type&lt;/span&gt;

    &lt;span class=&quot;cm&quot;&gt;/* fmt chunk */&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;fmt &quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// fmt id&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeInt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Integer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;));&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// fmt chunk size&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeShort&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;));&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// format: 1(PCM)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeShort&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;));&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// channels: 1&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeInt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Integer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;16000&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;));&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// samples per second&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeInt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Integer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16000&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)));&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// BPSecond&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeShort&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)));&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// BPSample&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeShort&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;short&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)));&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// bPSample&lt;/span&gt;

    &lt;span class=&quot;cm&quot;&gt;/* data chunk */&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;data&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// data id&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeInt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// data chunk size *PLACEHOLDER*&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;Log&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;d&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TAG&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;wav path: &quot;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;err&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;private&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;void&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;fwrite&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RandomAccessFile&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;byte&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;offset&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;size&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;throws&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;IOException&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;offset&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;size&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;Log&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;d&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TAG&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;fwrite: &quot;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;size&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
&lt;span class=&quot;err&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;private&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;void&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;fclose&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RandomAccessFile&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;throws&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;IOException&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;try&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;seek&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;4&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// riff chunk size&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeInt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Integer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;length&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)));&lt;/span&gt;

        &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;seek&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;40&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;c1&quot;&gt;// data chunk size&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeInt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Integer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reverseBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;((&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;int&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;length&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;44&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)));&lt;/span&gt;

        &lt;span class=&quot;n&quot;&gt;Log&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;d&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TAG&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;wav size: &quot;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;length&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;());&lt;/span&gt;

    &lt;span class=&quot;err&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;finally&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;close&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;err&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;wav转pcm&quot;&gt;wav转pcm&lt;/h2&gt;
&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# 将文件头去掉，数据转成int型即可
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;numpy&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;wav2pcm&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;pcmfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;data_type&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;int16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;open&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;rb&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;seek&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;read&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;44&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;data&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;np&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;fromfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dtype&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;data_type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tofile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;pcmfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
&lt;h2 id=&quot;pcm转wav&quot;&gt;pcm转wav&lt;/h2&gt;
&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# 利用wave库，添加通道信息、采样位数、采样率等信息作为文件头，pcm数据直接写入即可
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;wave&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;pcm2wav&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;pcm_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;wav_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;channels&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bits&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;16&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sample_rate&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;16000&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;pcmf&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;open&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;pcm_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;rb&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;pcmdata&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;pcmf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;read&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;pcmf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;close&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
 
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bits&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;%&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;raise&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;ValueError&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;bits % 8 must == 0. now bits:&quot;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;bits&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
 
    &lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;wave&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;open&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;wav_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&apos;wb&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;setnchannels&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;channels&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;setsampwidth&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;bits&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;//&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;setframerate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sample_rate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;writeframes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;pcmdata&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;wavfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;close&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
</description>
        <pubDate>Thu, 13 Nov 2025 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2025/11/13/wav-pcm/</link>
        <guid isPermaLink="true">https://titron.github.io/2025/11/13/wav-pcm/</guid>
        
        <category>audio,</category>
        
        <category>AAC-LC，wav,</category>
        
        <category>pcm</category>
        
        
        <category>basic</category>
        
      </item>
    
      <item>
        <title>audio系统中，AAC-LC是什么</title>
        <description>&lt;ul id=&quot;markdown-toc&quot;&gt;
  &lt;li&gt;&lt;a href=&quot;#核心信息&quot; id=&quot;markdown-toc-核心信息&quot;&gt;核心信息&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;#aac-家族的其他成员&quot; id=&quot;markdown-toc-aac-家族的其他成员&quot;&gt;AAC 家族的其他成员&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;
&lt;strong&gt;AAC-LC&lt;/strong&gt; 是一个音频编码标准，它是 &lt;strong&gt;Advanced Audio Coding (AAC)&lt;/strong&gt; 的一个配置文件（Profile），全称为 &lt;strong&gt;AAC Low Complexity&lt;/strong&gt;，意为 &lt;strong&gt;低复杂度AAC&lt;/strong&gt;。

&lt;hr /&gt;

&lt;h2 id=&quot;核心信息&quot;&gt;核心信息&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;标准：&lt;/strong&gt; AAC-LC 是 ISO/IEC 13818-7（MPEG-2）和 ISO/IEC 14496-3（MPEG-4）标准的一部分，是一种&lt;strong&gt;有损数字音频压缩&lt;/strong&gt;的编码格式。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;定位：&lt;/strong&gt; 它是 &lt;strong&gt;AAC 的基本配置文件&lt;/strong&gt;，也是&lt;strong&gt;最常用和支持最广泛&lt;/strong&gt;的版本。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;性能：&lt;/strong&gt;
    &lt;ul&gt;
      &lt;li&gt;&lt;strong&gt;高音质，低码率：&lt;/strong&gt; AAC-LC 旨在取代 MP3 格式，在相同比特率下，它的&lt;strong&gt;音质通常优于 MP3&lt;/strong&gt;。在较低的比特率下也能提供出色的音频质量。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;低复杂度：&lt;/strong&gt; “Low Complexity”（低复杂度）意味着它&lt;strong&gt;对解码设备的计算要求较低&lt;/strong&gt;，因此广泛应用于移动设备、便携式音乐播放器和流媒体服务。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;用途：&lt;/strong&gt; 广泛用于音乐分发和数字广播，例如：
    &lt;ul&gt;
      &lt;li&gt;Apple 的 &lt;strong&gt;iPod、iTunes、QuickTime&lt;/strong&gt; 和 &lt;strong&gt;Apple Music&lt;/strong&gt;。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;YouTube&lt;/strong&gt; 流媒体服务。&lt;/li&gt;
      &lt;li&gt;各种&lt;strong&gt;手机、便携式音乐播放器&lt;/strong&gt;和&lt;strong&gt;车载收音机&lt;/strong&gt;。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;数字电视广播&lt;/strong&gt;（如日本的 ISDB）。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;aac-家族的其他成员&quot;&gt;AAC 家族的其他成员&lt;/h2&gt;

AAC 标准还有其他变体，它们在压缩效率、复杂度和延迟方面有所不同：

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;HE-AAC (High Efficiency AAC，也称作 AAC+)：&lt;/strong&gt;
    &lt;ul&gt;
      &lt;li&gt;它在 AAC-LC 的基础上结合了 &lt;strong&gt;SBR (Spectral Band Replication，频带复制)&lt;/strong&gt; 技术，能够在&lt;strong&gt;极低的比特率下保持较好的音质&lt;/strong&gt;，常用于移动应用和带宽有限的流媒体。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;HE-AAC v2：&lt;/strong&gt;
    &lt;ul&gt;
      &lt;li&gt;在 HE-AAC 的基础上增加了 &lt;strong&gt;PS (Parametric Stereo，参数立体声)&lt;/strong&gt; 技术，能以更低的比特率实现立体声效果。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;AAC-LD (Low Delay，低延迟)：&lt;/strong&gt;
    &lt;ul&gt;
      &lt;li&gt;针对&lt;strong&gt;实时双向通信&lt;/strong&gt;（如视频通话）设计，牺牲了部分压缩效率来换取极低的编解码延迟。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;AAC-Main (Main Profile)：&lt;/strong&gt;
    &lt;ul&gt;
      &lt;li&gt;AAC 最初的主配置文件，虽然压缩效率略高于 AAC-LC，但计算复杂度也更高，&lt;strong&gt;普及程度不如 AAC-LC&lt;/strong&gt;。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ol&gt;

简单来说，&lt;strong&gt;AAC-LC 是目前最主流和兼容性最好的 AAC 格式&lt;/strong&gt;，是高品质音频压缩的基石。
</description>
        <pubDate>Wed, 15 Oct 2025 00:00:00 +0000</pubDate>
        <link>https://titron.github.io/2025/10/15/AAC-LC/</link>
        <guid isPermaLink="true">https://titron.github.io/2025/10/15/AAC-LC/</guid>
        
        <category>audio,</category>
        
        <category>AAC-LC</category>
        
        
        <category>basic</category>
        
      </item>
    
  </channel>
</rss>
