Skip to content

Commit 7d0004d

Browse files
stephentoubname
authored andcommitted
Revise Embedding types' IsSupported and add vector ownership ctor (microsoft#1093)
### Motivation and Context Fixes microsoft#568 ### Description Consolidate IsSupported to just being on the static Embedding type. And add a ctor to Embedding that allows transferring an array rather than copying it, then use that ctor in a bunch of places where we deserialize a vector and then immediately hand it off to an embedding. (I think subsequently we should think about getting rid of this ctor and just having the single ctor store rather than copy the original... I don't think the semi-immutability buys us much here.) ### Contribution Checklist <!-- Before submitting this PR, please make sure: --> - [x] The code builds clean without any errors or warnings - [x] The PR follows SK Contribution Guidelines (https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) - [x] The code follows the .NET coding conventions (https://learn.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions) verified with `dotnet format` - [x] All unit tests pass, and I have added new tests where possible - [x] I didn't break anyone 😄
1 parent bb51c2a commit 7d0004d

18 files changed

Lines changed: 153 additions & 146 deletions

File tree

‎dotnet/src/Connectors/Connectors.AI.HuggingFace/TextEmbedding/HuggingFaceTextEmbeddingGeneration.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ private async Task<IList<Embedding<float>>> ExecuteEmbeddingRequestAsync(IList<s
107107

108108
var embeddingResponse = JsonSerializer.Deserialize<TextEmbeddingResponse>(body);
109109

110-
return embeddingResponse?.Embeddings?.Select(l => new Embedding<float>(l.Embedding!)).ToList()!;
110+
return embeddingResponse?.Embeddings?.Select(l => new Embedding<float>(l.Embedding!, transferOwnership: true)).ToList()!;
111111
}
112112
catch (Exception e) when (e is not AIException && !e.IsCriticalException())
113113
{

‎dotnet/src/Connectors/Connectors.AI.OpenAI/AzureSdk/ClientBase.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ private protected async Task<IList<Embedding<float>>> InternalGenerateTextEmbedd
113113

114114
EmbeddingItem x = response.Value.Data[0];
115115

116-
result.Add(new Embedding<float>(x.Embedding));
116+
result.Add(new Embedding<float>(x.Embedding, transferOwnership: true));
117117
}
118118

119119
return result;

‎dotnet/src/Connectors/Connectors.AI.OpenAI/CustomClient/OpenAIClientBase.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ private protected async Task<IList<Embedding<float>>> ExecuteTextEmbeddingReques
7171
"Embeddings not found");
7272
}
7373

74-
return result.Embeddings.Select(e => new Embedding<float>(e.Values)).ToList();
74+
return result.Embeddings.Select(e => new Embedding<float>(e.Values, transferOwnership: true)).ToList();
7575
}
7676

7777
/// <summary>

‎dotnet/src/Connectors/Connectors.Memory.CosmosDB/CosmosMemoryStore.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ public async Task DeleteCollectionAsync(string collectionName, CancellationToken
147147
{
148148
memoryRecord = MemoryRecord.FromJsonMetadata(
149149
result.MetadataString,
150-
new Embedding<float>(vector),
150+
new Embedding<float>(vector, transferOwnership: true),
151151
result.Id,
152152
result.Timestamp);
153153
}
@@ -309,7 +309,7 @@ private async IAsyncEnumerable<MemoryRecord> GetAllAsync(string collectionName,
309309
{
310310
yield return MemoryRecord.FromJsonMetadata(
311311
item.MetadataString,
312-
new Embedding<float>(vector),
312+
new Embedding<float>(vector, transferOwnership: true),
313313
item.Id,
314314
item.Timestamp);
315315
}

‎dotnet/src/Connectors/Connectors.Memory.Pinecone/PineconeDocumentExtensions.cs‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,18 @@ public static PineconeDocument ToPineconeDocument(this MemoryRecord memoryRecord
5959
/// </summary>
6060
/// <param name="pineconeDocument">Instance of <see cref="PineconeDocument"/>.</param>
6161
/// <returns>Instance of <see cref="MemoryRecord"/>.</returns>
62-
public static MemoryRecord ToMemoryRecord(this PineconeDocument pineconeDocument)
62+
public static MemoryRecord ToMemoryRecord(this PineconeDocument pineconeDocument) =>
63+
ToMemoryRecord(pineconeDocument, transferVectorOwnership: false);
64+
65+
/// <summary>
66+
/// Maps <see cref="PineconeDocument"/> instance to <see cref="MemoryRecord"/>.
67+
/// </summary>
68+
/// <param name="pineconeDocument">Instance of <see cref="PineconeDocument"/>.</param>
69+
/// <param name="transferVectorOwnership">Whether to allow the created embedding to store a reference to this instance.</param>
70+
/// <returns>Instance of <see cref="MemoryRecord"/>.</returns>
71+
internal static MemoryRecord ToMemoryRecord(this PineconeDocument pineconeDocument, bool transferVectorOwnership)
6372
{
64-
Embedding<float> embedding = new(pineconeDocument.Values);
73+
Embedding<float> embedding = new(pineconeDocument.Values, transferVectorOwnership);
6574

6675
string additionalMetadataJson = pineconeDocument.GetSerializedMetadata();
6776

‎dotnet/src/Connectors/Connectors.Memory.Pinecone/PineconeMemoryStore.cs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ public async IAsyncEnumerable<string> UpsertBatchToNamespaceAsync(
253253
withEmbedding,
254254
cancellationToken))
255255
{
256-
return record?.ToMemoryRecord();
256+
return record?.ToMemoryRecord(transferVectorOwnership: true);
257257
}
258258
}
259259
catch (HttpRequestException ex)
@@ -393,7 +393,7 @@ in documentIds.Select(
393393

394394
foreach (PineconeDocument? record in vectorDataList)
395395
{
396-
yield return record?.ToMemoryRecord();
396+
yield return record?.ToMemoryRecord(transferVectorOwnership: true);
397397
}
398398
}
399399

@@ -574,7 +574,7 @@ public async Task RemoveWithDocumentIdBatchAsync(
574574

575575
await foreach ((PineconeDocument, double) result in results.WithCancellation(cancellationToken))
576576
{
577-
yield return (result.Item1.ToMemoryRecord(), result.Item2);
577+
yield return (result.Item1.ToMemoryRecord(transferVectorOwnership: true), result.Item2);
578578
}
579579
}
580580

@@ -647,7 +647,7 @@ public async Task RemoveWithDocumentIdBatchAsync(
647647

648648
await foreach ((PineconeDocument, double) result in results.WithCancellation(cancellationToken))
649649
{
650-
yield return (result.Item1.ToMemoryRecord(), result.Item2);
650+
yield return (result.Item1.ToMemoryRecord(transferVectorOwnership: true), result.Item2);
651651
}
652652
}
653653

‎dotnet/src/Connectors/Connectors.Memory.Qdrant/QdrantMemoryStore.cs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ await this._qdrantClient.UpsertVectorsAsync(
142142

143143
return MemoryRecord.FromJsonMetadata(
144144
json: vectorData.GetSerializedPayload(),
145-
embedding: new Embedding<float>(vectorData.Embedding),
145+
embedding: new Embedding<float>(vectorData.Embedding, transferOwnership: true),
146146
key: vectorData.PointId);
147147
}
148148
catch (HttpRequestException ex)
@@ -196,7 +196,7 @@ public async IAsyncEnumerable<MemoryRecord> GetBatchAsync(string collectionName,
196196

197197
return MemoryRecord.FromJsonMetadata(
198198
json: vectorData.GetSerializedPayload(),
199-
embedding: new Embedding<float>(vectorData.Embedding));
199+
embedding: new Embedding<float>(vectorData.Embedding, transferOwnership: true));
200200
}
201201
catch (HttpRequestException ex)
202202
{
@@ -233,7 +233,7 @@ public async IAsyncEnumerable<MemoryRecord> GetWithPointIdBatchAsync(
233233
{
234234
yield return MemoryRecord.FromJsonMetadata(
235235
json: vectorData.GetSerializedPayload(),
236-
embedding: new Embedding<float>(vectorData.Embedding),
236+
embedding: new Embedding<float>(vectorData.Embedding, transferOwnership: true),
237237
key: vectorData.PointId);
238238
}
239239
}
@@ -349,7 +349,7 @@ public async Task RemoveWithPointIdBatchAsync(string collectionName, IEnumerable
349349
yield return (
350350
MemoryRecord.FromJsonMetadata(
351351
json: result.Value.Item1.GetSerializedPayload(),
352-
embedding: new Embedding<float>(result.Value.Item1.Embedding)),
352+
embedding: new Embedding<float>(result.Value.Item1.Embedding, transferOwnership: true)),
353353
result.Value.Item2);
354354
}
355355
} while (hasResult);

‎dotnet/src/SemanticKernel.Abstractions/AI/Embeddings/Embedding.cs‎

Lines changed: 47 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ public static Embedding<TEmbedding> Empty
2424
{
2525
get
2626
{
27-
if (!IsSupported)
27+
if (!Embedding.IsSupported<TEmbedding>())
2828
{
2929
ThrowNotSupportedEmbedding();
3030
}
@@ -40,17 +40,34 @@ public static Embedding<TEmbedding> Empty
4040
/// <exception cref="ArgumentException">An unsupported type is used as TEmbedding.</exception>
4141
/// <exception cref="ArgumentNullException">A <c>null</c> vector is passed in.</exception>
4242
[JsonConstructor]
43-
public Embedding(IEnumerable<TEmbedding> vector)
43+
public Embedding(IEnumerable<TEmbedding> vector) : this(vector, transferOwnership: false)
44+
{
45+
}
46+
47+
/// <summary>
48+
/// Initializes a new instance of the <see cref="Embedding{TEmbedding}"/> class that contains either a copy of or the reference to the specified collection.
49+
/// </summary>
50+
/// <param name="vector">The source data.</param>
51+
/// <param name="transferOwnership">
52+
/// <see langword="true"/> to transfer logical ownership of <paramref name="vector"/> to this instance; after doing so,
53+
/// the caller should no longer mutate the original array. <see langword="false"/> to instead make a copy of <paramref name="vector"/>.
54+
/// </param>
55+
/// <exception cref="ArgumentException">An unsupported type is used as TEmbedding.</exception>
56+
/// <exception cref="ArgumentNullException">A <c>null</c> vector is passed in.</exception>
57+
public Embedding(IEnumerable<TEmbedding> vector, bool transferOwnership)
4458
{
4559
Verify.NotNull(vector);
4660

47-
if (!IsSupported)
61+
if (!Embedding.IsSupported<TEmbedding>())
4862
{
4963
ThrowNotSupportedEmbedding();
5064
}
5165

52-
// Create a local, protected copy
53-
this._vector = vector.ToArray();
66+
// Create a local, protected copy if transferOwnership is false or if the vector is not an array.
67+
// If the vector is an array and transferOwnership is true, then we can use the array directly.
68+
this._vector =
69+
transferOwnership && vector is TEmbedding[] array ? array :
70+
vector.ToArray();
5471
}
5572

5673
private static void ThrowNotSupportedEmbedding() =>
@@ -62,13 +79,6 @@ private static void ThrowNotSupportedEmbedding() =>
6279
[JsonPropertyName("vector")]
6380
public IEnumerable<TEmbedding> Vector => this._vector ?? Array.Empty<TEmbedding>();
6481

65-
/// <summary>
66-
/// Gets a value that indicates whether <typeparamref name="TEmbedding"/> is supported.
67-
/// </summary>
68-
[JsonIgnore]
69-
[SuppressMessage("Design", "CA1000:Do not declare static members on generic types", Justification = "Following 'IsSupported' pattern of System.Numerics.")]
70-
public static bool IsSupported => typeof(TEmbedding) == typeof(float) || typeof(TEmbedding) == typeof(double);
71-
7282
/// <summary>
7383
/// <c>true</c> if the vector is empty.
7484
/// </summary>
@@ -149,12 +159,12 @@ public bool Equals(Embedding<TEmbedding> other)
149159
}
150160

151161
/// <summary>
152-
/// Implicit creation of an <see cref="Embedding{TEmbedding}"/> object from an array of data.>
162+
/// Implicit creation of an <see cref="Embedding{TEmbedding}"/> object from an array of data.
153163
/// </summary>
154164
/// <param name="vector">An array of data.</param>
155165
public static explicit operator Embedding<TEmbedding>(TEmbedding[] vector)
156166
{
157-
return new Embedding<TEmbedding>(vector);
167+
return new Embedding<TEmbedding>(vector, transferOwnership: false);
158168
}
159169

160170
/// <summary>
@@ -185,12 +195,32 @@ public static explicit operator ReadOnlySpan<TEmbedding>(Embedding<TEmbedding> e
185195
}
186196

187197
/// <summary>
188-
/// Static class containing the supported types for <see cref="Embedding{TEmbedding}"/>.
198+
/// Provides functionality related to <see cref="Embedding{TEmbedding}"/>.
189199
/// </summary>
190200
public static class Embedding
191201
{
192202
/// <summary>
193-
/// Types supported by the <see cref="Embedding{TEmbedding}"/> struct.
203+
/// Gets whether the specified <typeparamref name="TEmbedding"/> is supported for use with <see cref="Embedding{TEmbedding}"/>.
204+
/// </summary>
205+
/// <typeparam name="TEmbedding">The type to be checked.</typeparam>
206+
/// <returns>
207+
/// <see langword="true"/> if the type is supported; otherwise, <see langword="true"/>.
208+
/// Currently only <see cref="Single"/> and <see cref="Double"/> are supported.
209+
/// </returns>
210+
public static bool IsSupported<TEmbedding>() => typeof(TEmbedding) == typeof(float) || typeof(TEmbedding) == typeof(double);
211+
212+
/// <summary>
213+
/// Gets whether the specified <paramref name="type"/> is supported for use with <see cref="Embedding{TEmbedding}"/>.
214+
/// </summary>
215+
/// <param name="type">The type to be checked.</param>
216+
/// <returns>
217+
/// <see langword="true"/> if the type is supported; otherwise, <see langword="true"/>.
218+
/// Currently only <see cref="Single"/> and <see cref="Double"/> are supported.
219+
/// </returns>
220+
public static bool IsSupported(Type type) => type == typeof(float) || type == typeof(double);
221+
222+
/// <summary>
223+
/// Gets an enumerable of the types supported by the <see cref="Embedding{TEmbedding}"/> struct.
194224
/// </summary>
195-
public static readonly Type[] SupportedTypes = { typeof(float), typeof(double) };
225+
public static IEnumerable<Type> SupportedTypes { get; } = Array.AsReadOnly(new Type[] { typeof(float), typeof(double) });
196226
}

‎dotnet/src/SemanticKernel.UnitTests/AI/Embeddings/EmbeddingTests.cs‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ public void ItCreatesEmptyEmbedding()
8080
// Assert
8181
Assert.Empty(target.Vector);
8282
Assert.Equal(0, target.Count);
83-
Assert.False(Embedding<int>.IsSupported);
83+
Assert.False(Embedding.IsSupported<int>());
8484
}
8585

8686
[Fact]
@@ -121,4 +121,13 @@ public void ItDoesntCopyVectorWhenCastingToSpan()
121121
Assert.False(Unsafe.AreSame(ref MemoryMarshal.GetReference(span1), ref MemoryMarshal.GetArrayDataReference(this._vector)));
122122
Assert.True(Unsafe.AreSame(ref MemoryMarshal.GetReference(span1), ref MemoryMarshal.GetReference(span2)));
123123
}
124+
125+
[Fact]
126+
public void ItTransfersOwnershipWhenRequested()
127+
{
128+
// Assert
129+
Assert.False(ReferenceEquals(_vector, new Embedding<float>(_vector).Vector));
130+
Assert.False(ReferenceEquals(_vector, new Embedding<float>(_vector, transferOwnership: false).Vector));
131+
Assert.True(ReferenceEquals(_vector, new Embedding<float>(_vector, transferOwnership: true).Vector));
132+
}
124133
}

‎dotnet/src/SemanticKernel.UnitTests/VectorOperations/VectorOperationTests.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ public class VectorOperationTests
2121
public void ItOnlySupportsFPDataTypes()
2222
{
2323
// Arrange
24-
var target = SupportedTypes.Types;
24+
var target = Embedding.SupportedTypes;
2525

2626
// Assert
2727
Assert.Equal(2, target.Count());

0 commit comments

Comments
 (0)