Added docs and test for half-precision indexing with Django

Author: ankane

README.md

@@ -133,6 +133,31 @@ class Item(models.Model):
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+#### Half-Precision Indexing
+
+Index vectors at half-precision
+
+```python
+from django.contrib.postgres.indexes import OpClass
+from django.db.models.functions import Cast
+from pgvector.django import HalfVectorField
+
+index = HnswIndex(
+    OpClass(Cast('embedding', HalfVectorField(dimensions=3)), name='halfvec_l2_ops'),
+    name='my_index',
+    m=16,
+    ef_construction=64
+)
+```
+
+Note: Add `'django.contrib.postgres'` to `INSTALLED_APPS` to use `OpClass`
+
+Get the nearest neighbors
+
+```python
+Item.objects.order_by(L2Distance(Cast('embedding', HalfVectorField(dimensions=3)), [3, 1, 2]))[:5]
+```
+
 ## SQLAlchemy
 
 Enable the extension

tests/test_django.py

@@ -1,6 +1,7 @@
 import django
 from django.conf import settings
 from django.contrib.postgres.fields import ArrayField
+from django.contrib.postgres.indexes import OpClass
 from django.core import serializers
 from django.db import connection, migrations, models
 from django.db.models import Avg, Sum, FloatField, DecimalField
@@ -38,7 +39,12 @@
                 'level': 'WARNING'
             }
         }
-    }
+    },
+    # needed for OpClass
+    # https://docs.djangoproject.com/en/5.1/ref/contrib/postgres/indexes/#opclass-expressions
+    INSTALLED_APPS=[
+        'django.contrib.postgres'
+    ]
 )
 django.setup()
 
@@ -67,6 +73,12 @@ class Meta:
                 m=16,
                 ef_construction=64,
                 opclasses=['vector_l2_ops']
+            ),
+            HnswIndex(
+                OpClass(Cast('embedding', HalfVectorField(dimensions=3)), name='halfvec_l2_ops'),
+                name='hnsw_half_precision_idx',
+                m=16,
+                ef_construction=64
             )
         ]
 
@@ -99,6 +111,10 @@ class Migration(migrations.Migration):
         migrations.AddIndex(
             model_name='item',
             index=pgvector.django.HnswIndex(fields=['embedding'], m=16, ef_construction=64, name='hnsw_idx', opclasses=['vector_l2_ops']),
+        ),
+        migrations.AddIndex(
+            model_name='item',
+            index=pgvector.django.HnswIndex(OpClass(Cast('embedding', HalfVectorField(dimensions=3)), name='halfvec_l2_ops'), m=16, ef_construction=64, name='hnsw_half_precision_idx'),
         )
     ]
 
@@ -473,3 +489,10 @@ def test_numeric_array(self):
         assert [v.id for v in items] == [1, 3, 2]
         assert [v.distance for v in items] == [0, 1, sqrt(3)]
         assert items[1].numeric_embedding == [1, 1, 2]
+
+    def test_half_precision(self):
+        create_items()
+        distance = L2Distance(Cast('embedding', HalfVectorField(dimensions=3)), [1, 1, 1])
+        items = Item.objects.annotate(distance=distance).order_by(distance)
+        assert [v.id for v in items] == [1, 3, 2]
+        assert [v.distance for v in items] == [0, 1, sqrt(3)]