https://stackoverflow.com/questions/74004965/valueerror-assignment-destination-is-read-only


大坑，给入前直接 deepcopy一下，不然numpy会报错，还难定位。

ValueError: assignment destination is read-only

https://huggingface2.notion.site/How-to-split-Flux-transformer-and-run-inference-aa1583ad23ce47a78589a79bb9309ab0




# 如何拆分Flux变换器并进行推理？

***作者：Sayak Paul***

扩散系统不是单一的整体模型，而是一系列相互连接的模型。例如，Stable Diffusion系列模型（及类似的模型）包含一个文本编码器、一个去噪器和一个VAE（变分自编码器）。还有一个非参数组件——噪声调度器。

现代扩散系统，如[Flux](https://blackforestlabs.ai/announcing-black-forest-labs/)，涉及多个文本编码器，一个作为去噪器的大型扩散变换器，最后是一个VAE。显然，使用这样的系统进行推理在消费者级GPU上是一个令人头疼的任务。

本文将展示如何解耦扩散系统的不同阶段（文本编码、去噪和解码），并在可用时将其计算拆分到多个（消费者级）GPU上。这里假设我们有两个16GB的GPU。

我们的测试平台是`Flux.1-Dev` [模型](https://huggingface.co/black-forest-labs/FLUX.1-dev)。该模型包含：

- 两个文本编码器：
  - T5-xxl
  - CLIP-L
- 一个扩散变换器（具有12.5B参数）
- 一个VAE

如果我们拥有两个16GB的GPU，那么我们无法直接进行推理。我们必须使用某种量化技术或其他模型拆分技巧。本文将采用后者。


![](https://www.dong-blog.fun/static/img/91895e249f80cb445544ce98fbbdbab9.image.webp)

### 文本编码

给定输入文本提示，我们首先计算文本嵌入。为此，我们只需要两个文本编码器和它们各自的分词器。我们将这两个文本编码器分别保存在两个GPU上。以下是实现代码：

```python
from diffusers import FluxPipeline
import torch 

ckpt_id = "black-forest-labs/FLUX.1-dev"
prompt = "a photo of a dog with cat-like look"

pipeline = FluxPipeline.from_pretrained(
    ckpt_id,
    transformer=None,
    vae=None,
    device_map="balanced",
    max_memory={0: "16GB", 1: "16GB"},
    torch_dtype=torch.bfloat16
)

with torch.no_grad():
    print("Encoding prompts.")
    prompt_embeds, pooled_prompt_embeds, text_ids = pipeline.encode_prompt(
        prompt=prompt, prompt_2=None, max_sequence_length=512
    )
```

## 去噪

一旦文本嵌入计算完成，我们可以释放文本编码器并释放GPU内存来加载扩散变换器。如前所述，扩散变换器有12.5B参数，是目前可用的最大的开放扩散变换器。即使使用如BFloat16这样降低精度的方法，我们也无法将其完全加载到16GB的显存中。因此，我们将把它拆分到两个16GB的GPU上。

首先，我们使用device_map="auto"加载变换器，让accelerate自动决定如何最佳地将模型拆分到GPU、CPU和磁盘上。尽管如此，我们仍希望尽量减少CPU和磁盘之间的数据移动。


```python
from diffusers import FluxTransformer2DModel
import torch 

transformer = FluxTransformer2DModel.from_pretrained(
    ckpt_id, 
    subfolder="transformer",
    device_map="auto",
    max_memory={0: "16GB", 1: "16GB"},
    torch_dtype=torch.bfloat16
)
```

如果我们从上面的代码中打印 `transformer.hf_device_map`，它将显示 `transformer` 每个模块在设备上的拆分情况。

接下来，我们可以将 `transformer` 集成到去噪过程中。我们加载 `FluxPipeline` 并传入我们之前加载的 `transformer`，但是将其他模型级组件（如文本编码器和VAE）设置为 `None`。

```python
pipeline = FluxPipeline.from_pretrained(
    ckpt_id,
    text_encoder=None,
    text_encoder_2=None,
    tokenizer=None,
    tokenizer_2=None,
    vae=None,
    transformer=transformer,
    torch_dtype=torch.bfloat16
)

print("Running denoising.")
height, width = 768, 1360
# No need to wrap it up under `torch.no_grad()` as pipeline call method
# is already wrapped under that.
latents = pipeline(
    prompt_embeds=prompt_embeds,
    pooled_prompt_embeds=pooled_prompt_embeds,
    num_inference_steps=50,
    guidance_scale=3.5,
    height=height,
    width=width,
    output_type="latent",
).images
```
### 解码并获取最终图像

这是图像生成过程的最后阶段，我们需要解码从前一阶段计算得到的潜在变量（latents）。由于VAE（变分自编码器）通常比较小，因此我们可以将其加载到单个16GB的GPU上进行处理。


```python
from diffusers import AutoencoderKL
from diffusers.image_processor import VaeImageProcessor
import torch 

vae = AutoencoderKL.from_pretrained(ckpt_id, subfolder="vae", torch_dtype=torch.bfloat16).to("cuda")
vae_scale_factor = 2 ** (len(vae.config.block_out_channels))
image_processor = VaeImageProcessor(vae_scale_factor=vae_scale_factor)

with torch.no_grad():
    print("Running decoding.")
    latents = FluxPipeline._unpack_latents(latents, height, width, vae_scale_factor)
    latents = (latents / vae.config.scaling_factor) + vae.config.shift_factor

    image = vae.decode(latents, return_dict=False)[0]
    image = image_processor.postprocess(image, output_type="pil")
    image[0].save("split_transformer.png")
```

## 完整代码片段


```python
from diffusers import FluxPipeline, AutoencoderKL, FluxTransformer2DModel
from diffusers.image_processor import VaeImageProcessor 
import torch 
import gc 

def flush():
    gc.collect()
    torch.cuda.empty_cache()
    torch.cuda.reset_max_memory_allocated()
    torch.cuda.reset_peak_memory_stats()

ckpt_id = "black-forest-labs/FLUX.1-dev"
prompt = "a photo of a dog with cat-like look"

pipeline = FluxPipeline.from_pretrained(
    ckpt_id,
    transformer=None,
    vae=None,
    device_map="balanced",
    max_memory={0: "16GB", 1: "16GB"},
    torch_dtype=torch.bfloat16
)
print(pipeline.hf_device_map)

with torch.no_grad():
    print("Encoding prompts.")
    prompt_embeds, pooled_prompt_embeds, text_ids = pipeline.encode_prompt(
        prompt=prompt, prompt_2=None, max_sequence_length=512
    )

print(prompt_embeds.shape)

del pipeline.text_encoder
del pipeline.text_encoder_2
del pipeline.tokenizer
del pipeline.tokenizer_2
del pipeline

flush()

transformer = FluxTransformer2DModel.from_pretrained(
    ckpt_id, 
    subfolder="transformer",
    device_map="auto",
    max_memory={0: "16GB", 1: "16GB"},
    torch_dtype=torch.bfloat16
)
print(transformer.hf_device_map)
pipeline = FluxPipeline.from_pretrained(
    ckpt_id,
    text_encoder=None,
    text_encoder_2=None,
    tokenizer=None,
    tokenizer_2=None,
    vae=None,
    transformer=transformer,
    torch_dtype=torch.bfloat16
)

print("Running denoising.")
height, width = 768, 1360
# No need to wrap it up under `torch.no_grad()` as pipeline call method
# is already wrapped under that.
latents = pipeline(
    prompt_embeds=prompt_embeds,
    pooled_prompt_embeds=pooled_prompt_embeds,
    num_inference_steps=50,
    guidance_scale=3.5,
    height=height,
    width=width,
    output_type="latent",
).images
print(latents.shape)

del pipeline.transformer
del pipeline

flush()

vae = AutoencoderKL.from_pretrained(ckpt_id, subfolder="vae", torch_dtype=torch.bfloat16).to("cuda")
vae_scale_factor = 2 ** (len(vae.config.block_out_channels))
image_processor = VaeImageProcessor(vae_scale_factor=vae_scale_factor)

with torch.no_grad():
    print("Running decoding.")
    latents = FluxPipeline._unpack_latents(latents, height, width, vae_scale_factor)
    latents = (latents / vae.config.scaling_factor) + vae.config.shift_factor

    image = vae.decode(latents, return_dict=False)[0]
    image = image_processor.postprocess(image, output_type="pil")
    image[0].save("split_transformer.png")
```

flux diffuser 分卡切分运行

https://github.com/hiyouga/LLaMA-Factory/issues/3773





格式：

```bash
[
  {
    "text": "123124124"
  },
  {
    "text": "123124124"
  }
  
 ]
```

用alpaca格式的训练是如何转成c4_demo.json的格式？

是instruction+input+ouput=>text.

不要求很多，c4_demo.json约有128条。



llamafactory-cli export my_examples/auto_gptq.yaml量化

auto_gptq.yaml为：


```bash
model_name_or_path: export_output/chat_and_sft/sft_qwen72b_300_chat_v33/
template: qwen

### export
export_dir: export_output/chat_and_sft/sft_qwen72b_300_chat_v33_gptq/
export_quantization_bit: 4
export_quantization_dataset: src/c4_demo.json
export_size: 2
export_device: cpu
export_legacy_format: false
```

llama-factory  量化数据要求 c4_demo.json

动态离线量化方法、静态离线量化方法和量化训练方法是什么区别？




https://paddlelite.paddlepaddle.org.cn/user_guides/quant_aware.html



![](https://www.dong-blog.fun/static/img/b42f38c34600691fd45676292ac472e1.image.webp)


![](https://www.dong-blog.fun/static/img/ebf0d8276937b668a73bdc261ef06007.image.webp)


https://paddlelite.paddlepaddle.org.cn/user_guides/quant/quant_post_dynamic_demo.html


## 1. 动态离线量化

动态离线量化方法简单易用，不需要校准数据，主要用于减小模型体积，无法明显提升预测速度。 


## 2. 静态离线量化方法

静态离线量化通过利用少量校准数据计算量化因子，能够快速生成量化后的模型。此量化模型可用于预测推理，显著降低计算负担、内存占用，并减少模型文件大小。
 
静态离线量化包括两种常见的量化因子计算方法：非饱和量化和饱和量化。

1.非饱和量化方法：该方法计算 Tensor 的绝对值最大值（abs_max），并将其映射为 127。
2.饱和量化方法：采用 KL 散度来确定一个合适的阈值 T（0 &lt; T &lt; abs_max），将其映射为 127。

通常，待量化操作（Op）的权重采用非饱和量化方法，而待量化操作的激活（如输入和输出）则使用饱和量化方法。
使用条件：

- 已训练好的预测模型
- 少量校准数据（例如：100-500 张图像）

缺点：

- 对于某些模型，特别是计算量较小或本身较为精简的模型，量化后可能会导致一定的精度损失。


## 3. 量化训练
1. 简介
量化训练是通过较多的训练数据对已经训练好的模型进行量化的方法。此过程模拟量化操作，在训练阶段更新权重，以减少量化误差，从而提升量化后模型的精度。
使用条件：

- 已有预训练模型
- 较为充足的训练数据（通常大于 5000 张图像）

优势：

- 有效降低计算量，减少内存占用，减小模型大小
- 量化后模型精度较少受影响

缺点：

- 对数据量和硬件要求较高，使用门槛较高。

建议首先使用“静态离线量化”方法对模型进行量化，验证精度后再考虑使用量化训练。如果静态量化后的模型精度不满足需求，再采用量化训练以优化精度。


## transformer 反量化

量化后的模型输出都要反量化才会得到浮点数值，一般框架里都带了，所以不用我们操作。

量化方法的辨析-动态离线量化方法、静态离线量化方法和量化训练方法是什么区别？

gxdx-单片机实验-呼吸灯-stm32 Proteus-实验报告

# 安装指南

## 1. 安装步骤

1. **视频教程**：[点击这里查看教程](https://www.bilibili.com/video/BV1AT421q76R/?vd_source=01d48741bf4b441465aae4f2a5c8e70a)





2. 获取安装包后，解压文件时输入密码：`jsmcu`

3. 双击 `Proteus817Setup.exe` 开始安装。  
   在安装过程中，请记住自己的安装路径。我的安装路径为：

   ```
   C:\Program Files (x86)\Labcenter Electronics\Proteus 8 Professional
   ```

   如下图所示：

   ![安装路径截图](https://www.dong-blog.fun/static/img/ecf8837e9e7cd57fa1ac9c99ec5e3847.image.webp)

4. 按照安装提示完成安装，安装完成后，桌面会出现图标。  
   双击图标打开 Proteus，如果没有出现错误提示，则说明安装成功。  
   如果出现警告提示或无法进入主页面，通常是由于用户名含有中文等原因导致的。

---

## 2. 汉化步骤

1. 如果您已成功打开 Proteus，请先关闭软件。

2. 然后将 `Translations` 文件夹中的所有子文件复制到以下路径：

   ```
   C:\Program Files (x86)\Labcenter Electronics\Proteus 8 Professional\Translations
   ```

3. 系统会提示是否替换文件，选择“是”进行替换。

4. 完成后，再次打开 Proteus，您将看到已经汉化完成的软件界面。

---

## 3. 测试验证

1. 打开一个 Proteus 仿真文件，如果看到小灯闪烁，说明软件安装并配置正确，可以正常使用。

Proteus 8.17 软件安装，汉化

# 2024年单片机实验

## 实验目的：
1. 掌握STM32编程基本操作。
2. 掌握PWM控制输出。
3. 掌握矩阵键盘工作原理及按键基本操作。
4. 掌握STM32串口通讯，并与上位机通讯。
5. 掌握LCD12864显示工作原理及基本操作。



---

## 实验任务：
1. 实现PWM呼吸灯，定时器产生PWM，控制实验板上的LED灯亮灭；
2. 通过任意两个按键切换PWM呼吸灯输出到两个不同的LED灯，实现亮灭效果；
3. 通过串口助手与LCD12864显示当前正在亮灭的LED是哪个，例如：LED P1.3 或 LED P1.4。

---

## 实验资料：
可通过口袋实验室慕课平台下载安装包、说明书及例程等，在一年级第一个月的附件中。

---

## 实验要求：
- 拿到 **2024年10月21日** 实验任务书后，即可展开自行实验。
- **12月10日前** 提交完整资料包，包含以下内容：
  - 实验报告（电子版，含流程图、核心逻辑程序代码及注释）
  - 实验源程序（可执行文件）
  - 实验心得（遇到的问题及解决方法）
  
  **实验报告** 中需附上关键核心逻辑程序及注释，并附上实验效果图。

- **资料包命名规则**：
  姓名-班级-学号 （请确保命名正确）

---

## 相关讲解资料：
- **关于STM32串口通信**：
  - [上位机如何与STM32进行串口通信](https://www.bilibili.com/video/BV1C64y1f7Qa?vd_source=23b04901c28af476f377115544178cf1)

- **关于STM32呼吸灯**：
  - [STM32呼吸灯教程](https://blog.csdn.net/TSC1235/article/details/132913039)

- **关于STM32矩阵键盘**：
  - [STM32矩阵键盘教程](https://blog.csdn.net/Jaye513/article/details/130516823)

- **关于LCD12864（51）**：
  - [【51单片机系列】proteus中的LCD12864液晶屏](https://blog.csdn.net/TSC1235/article/details/132913039)

- **关于Proteus仿真教程：基于STM32的LCD液晶显示**：
  - [Proteus仿真教程：LCD液晶显示](https://www.bilibili.com/video/BV15V411Y7En?vd_source=23b04901c28af476f377115544178cf1)



## PWM引脚选择


![](https://www.dong-blog.fun/static/img/b18ad39c01161d07c88cc126153d2b72.image.webp)

## 效果

按键PB14 控制PA6 的PWM点亮，同时PA7一定会熄灭。

按键PB15 控制PA7 的PWM点亮，同时PA6一定会熄灭。

屏幕显示的是当前亮的哪一个灯。

示波器显示的是当前PWM的占空比，呼吸灯就是占空比越高，小灯会亮，反之则更暗。

![](https://www.dong-blog.fun/static/img/b1a741dfe2cb574c065f435277d7b5de.image.webp)


## 代码

代码加QQ 742971636

gxdx-单片机实验-呼吸灯-stm32 Proteus仿真

Milvus使用教程（五）总结

## **索引向量字段**

本指南将引导您完成在集合中创建和管理向量字段索引的基本操作。

**概述**

Milvus利用存储在索引文件中的元数据，将数据组织成一种专门的结构，从而在搜索或查询时加速所请求信息的检索。



Milvus提供了多种索引类型和度量标准，用于对字段值进行排序，以实现高效的相似性搜索。下表列出了支持的索引类型和度量标准，适用于不同的向量字段类型。目前，Milvus支持多种类型的向量数据，包括浮点嵌入（通常称为浮点向量或密集向量）、二进制嵌入（也称为二进制向量）和稀疏嵌入（也称为稀疏向量）。有关详细信息，请参阅内存索引和相似性度量。


![](https://www.dong-blog.fun/static/img/e587406eb7445c6917f7fd49054d1e5a.image.webp)


![](https://www.dong-blog.fun/static/img/ceb793a6344dc29137d9180685ebc4a7.image.webp)


![](https://www.dong-blog.fun/static/img/224682c7e42b57afde5c231c18626b64.image.webp)



建议为频繁访问的向量字段和标量字段创建索引。

**准备工作**

如在“管理集合”中所述，如果在创建集合时指定以下任何条件，Milvus将自动生成索引并将其加载到内存中：

- 向量字段的维度和度量类型，或
- 模式和索引参数。

以下代码片段通过现有代码连接到Milvus实例，并创建一个集合而不指定索引参数。在这种情况下，集合没有索引，并且尚未加载。

为了准备索引，使用`MilvusClient`连接到Milvus服务器，并通过`create_schema()`、`add_field()`和`create_collection()`设置集合。

```python
from pymilvus import MilvusClient, DataType

# 1. 设置Milvus客户端
client = MilvusClient(
    uri="http://localhost:19530"
)

# 2. 创建模式
# 2.1. 创建模式
schema = MilvusClient.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

# 2.2. 向模式中添加字段
schema.add_field(field_name="id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="vector", datatype=DataType.FLOAT_VECTOR, dim=5)

# 3. 创建集合
client.create_collection(
    collection_name="customized_setup", 
    schema=schema, 
)
```

**索引集合**

要为集合创建索引或为集合建立索引，使用`prepare_index_params()`准备索引参数，并使用`create_index()`创建索引。

```python
# 4.1. 设置索引参数
index_params = MilvusClient.prepare_index_params()

# 4.2. 在向量字段上添加索引
index_params.add_index(
    field_name="vector",
    metric_type="COSINE",
    index_type="IVF_FLAT",
    index_name="vector_index",
    params={ "nlist": 128 }
)

# 4.3. 创建索引文件
client.create_index(
    collection_name="customized_setup",
    index_params=index_params,
    sync=False  # 是否等待索引创建完成后再返回，默认True
)
```

**参数说明**

| 参数名 | 描述 |
|------|-----|
| field_name | 要应用此对象的目标字段名称 |
| metric_type | 用于测量向量之间相似度的算法。可能的值有IP、L2、COSINE、JACCARD、HAMMING。此项仅适用于向量字段。有关详细信息，请参阅Milvus支持的索引。 |
| index_type | 用于在指定字段中排列数据的算法名称。适用的算法，请参阅内存索引和磁盘索引。 |
| index_name | 应用此对象后生成的索引文件名称 |
| params | 对指定索引类型的微调参数。有关可能的键和值范围，请参阅内存索引。 |
| collection_name | 已存在的集合名称 |
| index_params | 包含多个`IndexParam`对象的`IndexParams`对象 |
| sync | 控制索引的构建方式。有效值：True（默认值）：客户端等待索引构建完成后才返回。这意味着您在处理完成之前不会得到响应。False：客户端在接收到请求后立即返回，并在后台构建索引。要查看索引是否已完成构建，请使用`describe_index()`方法。 |

**注意**

目前，每个集合中的每个字段只能创建一个索引文件。

**检查索引详情**

创建索引后，您可以检查其详细信息。

要检查索引详情，使用`list_indexes()`列出索引名称，使用`describe_index()`获取索引详细信息。

```python
# 5. 描述索引
res = client.list_indexes(
    collection_name="customized_setup"
)

print(res)

# 输出
# [
#     "vector_index",
# ]

res = client.describe_index(
    collection_name="customized_setup",
    index_name="vector_index"
)

print(res)

# 输出
# {
#     "index_type": ,
#     "metric_type": "COSINE",
#     "field_name": "vector",
#     "index_name": "vector_index"
# }
```

您可以检查特定字段上创建的索引文件，并收集使用该索引文件的索引行数统计信息。

**删除索引**

如果不再需要某个索引，您可以将其删除。

在删除索引之前，确保已释放该索引。

要删除索引，使用`drop_index()`。

```python
# 6. 删除索引
client.drop_index(
    collection_name="customized_setup",
    index_name="vector_index"
)
```

**标量字段索引**

在Milvus中，标量索引用于通过特定的非向量字段值加速元过滤，类似于传统数据库的索引。本文将引导您创建和配置用于整数、字符串等字段的标量索引。

## 标量索引类型

1. **自动索引**：Milvus会根据标量字段的数据类型自动决定索引类型。当您不需要控制具体的索引类型时，可以使用自动索引。

2. **自定义索引**：您可以指定具体的索引类型，如倒排索引或位图索引。这为索引类型选择提供了更多的控制。

### 自动索引

要使用自动索引，在`add_index()`中省略`index_type`参数，Milvus会根据标量字段的类型推断出索引类型。

有关标量数据类型和默认索引算法之间的映射，请参阅**标量字段索引算法**。

```python
# 自动索引
client = MilvusClient(
    uri="http://localhost:19530"
)

index_params = MilvusClient.prepare_index_params()  # 准备一个空的 IndexParams 对象，无需指定任何索引参数

index_params.add_index(
    field_name="scalar_1",  # 要索引的标量字段名称
    index_type="",  # 索引类型，自动索引时留空或省略该参数
    index_name="default_index"  # 要创建的索引名称
)

client.create_index(
  collection_name="test_scalar_index",  # 指定集合名称
  index_params=index_params
)
```

### 自定义索引

要使用自定义索引，通过`add_index()`中的`index_type`参数指定特定的索引类型。

下面的示例创建了一个倒排索引，适用于标量字段`scalar_2`。

```python
index_params = MilvusClient.prepare_index_params()  # 准备一个 IndexParams 对象

index_params.add_index(
    field_name="scalar_2",  # 要索引的标量字段名称
    index_type="INVERTED",  # 要创建的索引类型
    index_name="inverted_index"  # 要创建的索引名称
)

client.create_index(
  collection_name="test_scalar_index",  # 指定集合名称
  index_params=index_params
)
```

### 方法和参数

#### `prepare_index_params()`

准备一个`IndexParams`对象。

#### `add_index()`

将索引配置添加到`IndexParams`对象中。

- `field_name`（字符串）：要索引的标量字段名称。
- `index_type`（字符串）：要创建的标量索引类型。对于隐式索引，留空或省略此参数。

对于自定义索引，`index_type`的有效值包括：

- **INVERTED**：（推荐）倒排索引由包含所有已分词单词的术语字典组成，单词按字母顺序排序。详细信息请参阅**标量索引**。
- **STL_SORT**：使用标准模板库排序算法对标量字段进行排序。仅支持数字字段（例如INT8、INT16、INT32、INT64、FLOAT、DOUBLE）。
- **Trie**：用于快速前缀搜索和检索的树形数据结构。支持VARCHAR字段。

- `index_name`（字符串）：要创建的标量索引的名称。每个标量字段支持一个索引。

#### `create_index()`

在指定的集合中创建索引。

- `collection_name`（字符串）：要创建索引的集合名称。
- `index_params`：包含索引配置的`IndexParams`对象。

### 验证结果

使用`list_indexes()`方法验证标量索引的创建：

```python
client.list_indexes(
    collection_name="test_scalar_index"  # 指定集合名称
)

# 输出：
# ['default_index', 'inverted_index']
```

### 限制

目前，标量索引支持以下数据类型：INT8、INT16、INT32、INT64、FLOAT、DOUBLE、BOOL、VARCHAR和ARRAY，但不支持JSON数据类型。

## **位图索引**

位图索引是一种高效的索引技术，旨在提高低基数标量字段查询的性能。基数指的是字段中不同值的数量，基数较小的字段被认为是低基数字段。

这种索引类型通过将字段值表示为紧凑的二进制格式，并对其执行高效的按位操作，从而帮助减少标量查询的检索时间。与其他类型的索引相比，位图索引在处理低基数字段时通常具有更高的空间效率和更快的查询速度。

### 概述

“位图”一词结合了“Bit”和“Map”两个词。Bit是计算机中最小的数据单位，它只能存储0或1的值。Map在此上下文中指的是根据应该分配给0和1的值来转换和组织数据的过程。

位图索引由两个主要组成部分构成：位图和键。键表示索引字段中的唯一值。对于每个唯一值，都有一个对应的位图。这些位图的长度等于集合中的记录数。位图中的每一位都对应集合中的一条记录。如果记录中索引字段的值与某个键匹配，则对应的位设为1；否则，设为0。

例如，考虑一个包含“Category”和“Public”字段的文档集合。我们希望检索属于“Tech”类别并且公开的文档。在这种情况下，位图索引的键是“Tech”和“Public”。

### 位图索引

如图所示，Category和Public的位图索引如下：

- **Tech**: [1, 0, 1, 0, 0]，表示只有第1个和第3个文档属于Tech类别。
- **Public**: [1, 0, 0, 1, 0]，表示只有第1个和第4个文档对公众开放。

为了找到同时满足这两个条件的文档，我们对这两个位图执行按位与（AND）操作：

- **Tech AND Public**: [1, 0, 0, 0, 0]

结果的位图 [1, 0, 0, 0, 0] 表明只有第一个文档（ID为1）同时满足这两个条件。通过使用位图索引和高效的按位操作，我们可以快速缩小搜索范围，从而避免扫描整个数据集。

### 创建位图索引

要在Milvus中创建位图索引，可以使用`create_index()`方法，并将`index_type`参数设置为"BITMAP"。

```python
from pymilvus import MilvusClient

index_params = client.create_index_params()  # 准备一个空的 IndexParams 对象，无需指定任何索引参数
index_params.add_index(
    field_name="category",  # 要索引的标量字段名称
    index_type="BITMAP",    # 要创建的索引类型
    index_name="category_bitmap_index"  # 要创建的索引名称
)

client.create_index(
    collection_name="my_collection",  # 指定集合名称
    index_params=index_params
)
```

在这个示例中，我们为`my_collection`集合中的`category`字段创建了一个位图索引。`add_index()`方法用于指定字段名称、索引类型和索引名称。

一旦位图索引创建完成，您可以在查询操作中使用`filter`参数，基于索引字段执行标量过滤。这使得您可以通过位图索引高效地缩小搜索结果的范围。有关更多信息，请参阅**元数据过滤**。

### 限制

位图索引仅支持非主键的标量字段。

字段的数据类型必须是以下之一：

- BOOL、INT8、INT16、INT32、INT64、VARCHAR
- ARRAY（元素类型必须是：BOOL、INT8、INT16、INT32、INT64、VARCHAR）

位图索引不支持以下数据类型：

- **FLOAT、DOUBLE**：浮动类型与位图索引的二进制特性不兼容。
- **JSON**：JSON数据类型具有复杂结构，不能有效地使用位图索引表示。

位图索引不适用于高基数字段（即具有大量不同值的字段）。

一般而言，位图索引在字段的基数小于500时最为有效。当基数超过此阈值时，位图索引的性能优势会降低，存储开销也会显著增加。

对于高基数字段，考虑使用其他索引技术（如倒排索引），具体选择应根据您的使用场景和查询要求。

## 使用GPU构建索引

本指南概述了如何在Milvus中构建支持GPU的索引，这可以显著提高在高吞吐量和高召回场景中的搜索性能。有关Milvus支持的GPU索引类型的详细信息，请参见GPU索引。

### 配置Milvus设置以控制GPU内存

Milvus使用一个全局的图形内存池来分配GPU内存。

Milvus配置文件中支持两个参数：`initMemSize` 和 `maxMemSize`。内存池的大小初始设置为`initMemSize`，并且在超过此限制后，会自动扩展到`maxMemSize`。

默认情况下，`initMemSize`是Milvus启动时可用GPU内存的一半，`maxMemSize`等于所有可用GPU内存。

直到Milvus 2.4.1版本（包括2.4.1），Milvus使用统一的GPU内存池。对于2.4.1之前的版本（包括2.4.1），建议将这两个值都设置为0。

```yaml
gpu:
  initMemSize: 0  # 设置初始内存池大小
  maxMemSize: 0  # maxMemSize设置最大内存使用限制。当内存使用超过initMemSize时，Milvus将尝试扩展内存池。
```

从Milvus 2.4.1版本开始，GPU内存池仅用于搜索过程中临时GPU数据。因此，建议将其设置为2048和4096。

```yaml
gpu:
  initMemSize: 2048  # 设置初始内存池大小
  maxMemSize: 4096  # maxMemSize设置最大内存使用限制。当内存使用超过initMemSize时，Milvus将尝试扩展内存池。
```

### 构建索引

以下示例演示了如何构建不同类型的GPU索引。

#### 准备索引参数

在设置GPU索引参数时，需要定义`index_type`、`metric_type`和`params`：

- `index_type`（字符串）：用于加速向量搜索的索引类型。有效选项包括GPU_CAGRA、GPU_IVF_FLAT、GPU_IVF_PQ和GPU_BRUTE_FORCE。
- `metric_type`（字符串）：用于衡量向量相似性的度量类型。有效选项包括IP和L2。
- `params`（字典）：特定索引的构建参数。此参数的有效选项取决于索引类型。

以下是不同索引类型的配置示例：

#### GPU_CAGRA索引

```python
index_params = {
    "metric_type": "L2",
    "index_type": "GPU_CAGRA",
    "params": {
        'intermediate_graph_degree': 64,
        'graph_degree': 32
    }
}
```

`params`的可能选项包括：

- `intermediate_graph_degree`（整数）：通过确定修剪前图的度来影响召回率和构建时间。推荐值为32或64。
- `graph_degree`（整数）：通过设置修剪后图的度来影响搜索性能和召回率。通常，它是`intermediate_graph_degree`的一半。两者之间的差异越大，构建时间越长。其值必须小于`intermediate_graph_degree`的值。
- `build_algo`（字符串）：选择修剪前图的生成算法。可能的选项：
  - `IVF_PQ`：提供较高的质量，但构建时间较长。
  - `NN_DESCENT`：提供更快的构建，但召回率可能较低。
- `cache_dataset_on_device`（字符串，“true” | “false”）：决定是否将原始数据集缓存到GPU内存中。设置为“true”可以通过优化搜索结果提高召回率，而设置为“false”则节省GPU内存。

#### GPU_IVF_FLAT 或 GPU_IVF_PQ索引

```python
index_params = {
    "metric_type": "L2",
    "index_type": "GPU_IVF_FLAT",  # 或 GPU_IVF_PQ
    "params": {
        "nlist": 1024
    }
}
```

`params`的选项与IVF_FLAT和IVF_PQ中的选项相同。

#### GPU_BRUTE_FORCE索引

```python
index_params = {
    'index_type': 'GPU_BRUTE_FORCE',
    'metric_type': 'L2',
    'params': {}
}
```

不需要额外的`params`配置。

#### 构建索引

配置好`index_params`中的索引参数后，调用`create_index()`方法来构建索引。

```python
# 获取现有集合
collection = Collection("YOUR_COLLECTION_NAME")

collection.create_index(
    field_name="vector",  # 用于构建索引的向量字段名称
    index_params=index_params
)
```

### 搜索

一旦构建了GPU索引，下一步是准备搜索参数，然后执行搜索。

#### 准备搜索参数

以下是不同索引类型的搜索参数配置示例：

##### GPU_BRUTE_FORCE索引

```python
search_params = {
    "metric_type": "L2",
    "params": {}
}
```

不需要额外的`params`配置。

##### GPU_CAGRA索引

```python
search_params = {
    "metric_type": "L2",
    "params": {
        "itopk_size": 128,
        "search_width": 4,
        "min_iterations": 0,
        "max_iterations": 0,
        "team_size": 0
    }
}
```

关键搜索参数包括：

- `itopk_size`：确定搜索过程中保留的中间结果的大小。较大的值可能提高召回率，但会影响搜索性能。它应该至少等于最终的top-k（限制）值，通常是2的幂（例如16、32、64、128）。
- `search_width`：指定搜索时进入CAGRA图的入口点数量。增加此值可以提高召回率，但可能影响搜索性能。
- `min_iterations` / `max_iterations`：这些参数控制搜索迭代过程。默认情况下，它们设置为0，CAGRA会自动根据`itopk_size`和`search_width`确定迭代次数。手动调整这些值可以帮助平衡性能和准确性。
- `team_size`：指定用于计算GPU上度量距离的CUDA线程数。常见的值是2的幂，最大为32（例如2、4、8、16、32）。它对搜索性能的影响较小。默认值为0，Milvus会根据向量维度自动选择`team_size`。

##### GPU_IVF_FLAT 或 GPU_IVF_PQ索引

```python
search_params = {
    "metric_type": "L2", 
    "params": {"nprobe": 10}
}
```

这两种索引类型的搜索参数与IVF_FLAT和IVF_PQ中使用的参数类似。有关更多信息，请参阅执行向量相似性搜索。

#### 执行搜索

使用`search()`方法在GPU索引上执行向量相似性搜索。

```python
# 将数据加载到内存
collection.load()

collection.search(
    data=[[query_vector]],  # 查询向量
    anns_field="vector",    # 向量字段名称
    param=search_params,
    limit=100  # 返回的结果数量
)
```

### 限制

使用GPU索引时，需要注意以下限制：

- 对于GPU_IVF_FLAT，`limit`的最大值为256。
- 对于GPU_IVF_PQ和GPU_CAGRA，`limit`的最大值为1024。
- 对于GPU_BRUTE_FORCE，`limit`的最大值没有固定限制，但建议不超过4096，以避免可能的性能问题。
- 当前，GPU索引不支持余弦距离。如果需要余弦距离，数据应先进行归一化，然后可以使用内积（IP）距离作为替代。
- GPU索引对内存不足保护（OOM）支持不完全，过多数据可能导致QueryNode崩溃。
- GPU索引不支持范围搜索和分组搜索等功能。

### 常见问题

#### 何时使用GPU索引？

GPU索引特别适用于需要高吞吐量或高召回率的场景。例如，在处理大批量数据时，GPU索引的吞吐量可以比CPU索引高出100倍以上。在较小批量的场景中，GPU索引的性能仍然显著优于CPU索引。此外，如果需要快速的数据插入，加入GPU可以显著加速索引的构建过程。

#### GPU索引（如CAGRA、GPU_IVF_PQ、GPU_IVF_FLAT和GPU_BRUTE_FORCE）适用于哪些场景？

- CAGRA索引适用于需要高性能的场景，但会消耗更多内存。
- GPU_IVF_PQ索引适用于内存受限的环境，尽管精度会有所降低，但可以减少存储需求。
- GPU_IVF_FLAT索引是一种平衡选项，提供了性能和

Milvus使用教程（四）管理索引

## 插入实体  

集合中的实体是共享相同字段集的数据记录。每个数据记录中的字段值构成一个实体。本节介绍如何将实体插入到集合中。



概述  
在Milvus中，实体是指集合中的数据记录，这些数据记录共享相同的模式（Schema），每一行中的字段数据构成一个实体。因此，同一集合中的实体具有相同的属性（例如字段名称、数据类型和其他约束）。

当向集合中插入实体时，只有当实体包含模式中定义的所有字段时，插入才会成功。插入的实体将按插入顺序进入名为_default的分区。假如某个分区已存在，也可以通过在插入请求中指定分区名称，将实体插入到该分区中。

Milvus还支持动态字段，以保持集合的可扩展性。当启用动态字段时，可以将模式中未定义的字段插入到集合中。这些字段及其值将作为键值对存储在名为$meta的保留字段中。有关动态字段的更多信息，请参见《动态字段》。

将实体插入集合  
在插入数据之前，您需要根据模式将数据组织成字典列表，每个字典代表一个实体，并包含所有在模式中定义的字段。如果集合启用了动态字段，则每个字典还可以包含未在模式中定义的字段。

在本节中，您将向以快速设置方式创建的集合中插入实体。通过这种方式创建的集合只有两个字段，分别为id和vector。此外，该集合已启用动态字段，因此示例代码中的实体包含一个未在模式中定义的字段——**color**。

```python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

data=[
    {"id": 0, "vector": [0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592], "color": "pink_8682"},
    {"id": 1, "vector": [0.19886812562848388, 0.06023560599112088, 0.6976963061752597, 0.2614474506242501, 0.838729485096104], "color": "red_7025"},
    {"id": 2, "vector": [0.43742130801983836, -0.5597502546264526, 0.6457887650909682, 0.7894058910881185, 0.20785793220625592], "color": "orange_6781"},
    {"id": 3, "vector": [0.3172005263489739, 0.9719044792798428, -0.36981146090600725, -0.4860894583077995, 0.95791889146345], "color": "pink_9298"},
    {"id": 4, "vector": [0.4452349528804562, -0.8757026943054742, 0.8220779437047674, 0.46406290649483184, 0.30337481143159106], "color": "red_4794"},
    {"id": 5, "vector": [0.985825131989184, -0.8144651566660419, 0.6299267002202009, 0.1206906911183383, -0.1446277761879955], "color": "yellow_4222"},
    {"id": 6, "vector": [0.8371977790571115, -0.015764369584852833, -0.31062937026679327, -0.562666951622192, -0.8984947637863987], "color": "red_9392"},
    {"id": 7, "vector": [-0.33445148015177995, -0.2567135004164067, 0.8987539745369246, 0.9402995886420709, 0.5378064918413052], "color": "grey_8510"},
    {"id": 8, "vector": [0.39524717779832685, 0.4000257286739164, -0.5890507376891594, -0.8650502298996872, -0.6140360785406336], "color": "white_9381"},
    {"id": 9, "vector": [0.5718280481994695, 0.24070317428066512, -0.3737913482606834, -0.06726932177492717, -0.6980531615588608], "color": "purple_4976"}
]

res = client.insert(
    collection_name="quick_setup",
    data=data
)

print(res)

# 输出
# {'insert_count': 10, 'ids': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}
```

将实体插入分区  
您还可以将实体插入到指定的分区中。以下代码假设您在集合中有一个名为`PartitionA`的分区。

```python
data=[
    {"id": 10, "vector": [0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592], "color": "pink_8682"},
    {"id": 11, "vector": [0.19886812562848388, 0.06023560599112088, 0.6976963061752597, 0.2614474506242501, 0.838729485096104], "color": "red_7025"},
    {"id": 12, "vector": [0.43742130801983836, -0.5597502546264526, 0.6457887650909682, 0.7894058910881185, 0.20785793220625592], "color": "orange_6781"},
    {"id": 13, "vector": [0.3172005263489739, 0.9719044792798428, -0.36981146090600725, -0.4860894583077995, 0.95791889146345], "color": "pink_9298"},
    {"id": 14, "vector": [0.4452349528804562, -0.8757026943054742, 0.8220779437047674, 0.46406290649483184, 0.30337481143159106], "color": "red_4794"},
    {"id": 15, "vector": [0.985825131989184, -0.8144651566660419, 0.6299267002202009, 0.1206906911183383, -0.1446277761879955], "color": "yellow_4222"},
    {"id": 16, "vector": [0.8371977790571115, -0.015764369584852833, -0.31062937026679327, -0.562666951622192, -0.8984947637863987], "color": "red_9392"},
    {"id": 17, "vector": [-0.33445148015177995, -0.2567135004164067, 0.8987539745369246, 0.9402995886420709, 0.5378064918413052], "color": "grey_8510"},
    {"id": 18, "vector": [0.39524717779832685, 0.4000257286739164, -0.5890507376891594, -0.8650502298996872, -0.6140360785406336], "color": "white_9381"},
    {"id": 19, "vector": [0.5718280481994695, 0.24070317428066512, -0.3737913482606834, -0.06726932177492717, -0.6980531615588608], "color": "purple_4976"}
]

res = client.insert(
    collection_name="quick_setup",
    partition_name="partitionA",
    data=data
)

print(res)

# 输出
# {'insert_count': 10, 'ids': [10, 11, 12, 13, 14, 15, 16, 17, 18, 19]}
```




## 插入或更新实体（Upsert Entities）


Upsert 操作结合了更新和插入数据的功能。Milvus 会通过检查主键是否存在来决定执行更新操作还是插入操作。本节将介绍如何进行实体的插入或更新，并阐述在不同场景下 Upsert 操作的具体行为。

#### 概述
当你需要更新集合中的实体，或不确定是进行更新还是插入时，可以尝试使用 Upsert 操作。在使用该操作时，必须确保 Upsert 请求中包含实体的主键，否则会出现错误。收到 Upsert 请求后，Milvus 将执行以下流程：

1. 检查集合的主键字段是否启用了 AutoId。
    - a. 如果启用了，Milvus 将使用自动生成的主键替换实体中的主键并插入数据。
    - b. 如果没有启用，Milvus 将使用实体中携带的主键进行数据插入。
2. 根据 Upsert 请求中实体的主键值执行删除操作。

### 在集合中插入或更新实体

本节介绍如何将实体插入或更新到通过快速设置方式创建的集合中。通过该方式创建的集合只有两个字段，分别是 `id` 和 `vector`。此外，该集合启用了动态字段，因此示例代码中的实体包含一个名为 `color` 的字段，这个字段在 Schema 中未定义。

```python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

data = [
    {"id": 0, "vector": [-0.619954382375778, 0.4479436794798608, -0.17493894838751745, -0.4248030059917294, -0.8648452746018911], "color": "black_9898"},
    {"id": 1, "vector": [0.4762662251462588, -0.6942502138717026, -0.4490002642657902, -0.628696575798281, 0.9660395877041965], "color": "red_7319"},
    {"id": 2, "vector": [-0.8864122635045097, 0.9260170474445351, 0.801326976181461, 0.6383943392381306, 0.7563037341572827], "color": "white_6465"},
    {"id": 3, "vector": [0.14594326235891586, -0.3775407299900644, -0.3765479013078812, 0.20612075380355122, 0.4902678929632145], "color": "orange_7580"},
    {"id": 4, "vector": [0.4548498669607359, -0.887610217681605, 0.5655081329910452, 0.19220509387904117, 0.016513983433433577], "color": "red_3314"},
    {"id": 5, "vector": [0.11755001847051827, -0.7295149788999611, 0.2608115847524266, -0.1719167007897875, 0.7417611743754855], "color": "black_9955"},
    {"id": 6, "vector": [0.9363032158314308, 0.030699901477745373, 0.8365910312319647, 0.7823840208444011, 0.2625222076909237], "color": "yellow_2461"},
    {"id": 7, "vector": [0.0754823906014721, -0.6390658668265143, 0.5610517334334937, -0.8986261118798251, 0.9372056764266794], "color": "white_5015"},
    {"id": 8, "vector": [-0.3038434006935904, 0.1279149203380523, 0.503958664270957, -0.2622661156746988, 0.7407627307791929], "color": "purple_6414"},
    {"id": 9, "vector": [-0.7125086947677588, -0.8050968321012257, -0.32608864121785786, 0.3255654958645424, 0.26227968923834233], "color": "brown_7231"}
]

res = client.upsert(
    collection_name='quick_setup',
    data=data
)

print(res)

# 输出
# {'upsert_count': 10}
```

### 在指定分区中插入或更新实体

你也可以将实体插入到指定的分区中。以下代码假设你在集合中有一个名为 `PartitionA` 的分区。

```python
data = [
    {"id": 10, "vector": [0.06998888224297328, 0.8582816610326578, -0.9657938677934292, 0.6527905683627726, -0.8668460657158576], "color": "black_3651"},
    {"id": 11, "vector": [0.6060703043917468, -0.3765080534566074, -0.7710758854987239, 0.36993888322346136, 0.5507513364206531], "color": "grey_2049"},
    {"id": 12, "vector": [-0.9041813104515337, -0.9610546012461163, 0.20033003106083358, 0.11842506351635174, 0.8327356724591011], "color": "blue_6168"},
    {"id": 13, "vector": [0.3202914977909075, -0.7279137773695252, -0.04747830871620273, 0.8266053056909548, 0.8277957187455489], "color": "blue_1672"},
    {"id": 14, "vector": [0.2975811497890859, 0.2946936202691086, 0.5399463833894609, 0.8385334966677529, -0.4450543984655133], "color": "pink_1601"},
    {"id": 15, "vector": [-0.04697464305600074, -0.08509022265734134, 0.9067184632552001, -0.2281912685064822, -0.9747503428652762], "color": "yellow_9925"},
    {"id": 16, "vector": [-0.9363075919673911, -0.8153981031085669, 0.7943039120490902, -0.2093886809842529, 0.0771191335807897], "color": "orange_9872"},
    {"id": 17, "vector": [-0.050451522820639916, 0.18931572752321935, 0.7522886192190488, -0.9071793089474034, 0.6032647330692296], "color": "red_6450"},
    {"id": 18, "vector": [-0.9181544231141592, 0.6700755998126806, -0.014174674636136642, 0.6325780463623432, -0.49662222164032976], "color": "purple_7392"},
    {"id": 19, "vector": [0.11426945899602536, 0.6089190684002581, -0.5842735738352236, 0.057050610092692855, -0.035163433018196244], "color": "pink_4996"}
]

res = client.upsert(
    collection_name="quick_setup",
    data=data,
    partition_name="partitionA"
)

print(res)

# 输出
# {'upsert_count': 10}
```

---


## 删除实体  
您可以通过过滤条件或主键删除不再需要的实体。

通过过滤条件删除实体  
在批量删除具有相同属性的多个实体时，可以使用过滤表达式。以下示例代码使用 `in` 运算符批量删除所有颜色字段为 `red` 和 `green` 的实体。您还可以使用其他运算符构造满足需求的过滤表达式。如需了解更多关于过滤表达式的信息，请参考[元数据过滤](#)。

```python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

res = client.delete(
    collection_name="quick_setup",
    # highlight-next-line
    filter="color in ['red_3314', 'purple_7392']"
)

print(res)

# Output
# {'delete_count': 2}
```

通过主键删除实体  
在大多数情况下，主键唯一标识一个实体。您可以通过在删除请求中设置其主键来删除实体。以下示例代码演示了如何删除主键为18和19的两个实体。

```python
res = client.delete(
    collection_name="quick_setup",
    # highlight-next-line
    ids=[18, 19]
)

print(res)

# Output
# {'delete_count': 2}
```

从分区中删除实体  
您还可以删除存储在特定分区中的实体。以下代码假设您的集合中有一个名为 `PartitionA` 的分区。

```python
res = client.delete(
    collection_name="quick_setup",
    ids=[18, 19],
    partition_name="partitionA"
)

print(res)

# Output
# {'delete_count': 2}
```