Adding needed Tokenizer's APIs #7047
Conversation
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #7047 +/- ##
==========================================
+ Coverage 68.81% 68.82% +0.01%
==========================================
Files 1255 1255
Lines 250248 250358 +110
Branches 25533 25550 +17
==========================================
+ Hits 172197 172304 +107
+ Misses 71442 71441 -1
- Partials 6609 6613 +4
Flags with carried forward coverage won't be shown. Click here to find out more.
|
| // '⭐' U-2B50 is mapped to IDs [2928, 99834] in the Tiktoken model. | ||
| // In other words, the character '⭐' with UTF-8 code point 0xE2, 0xAD, 0x90 will be mapped by Tiktoken as follows: 0xE2 to [2928] | ||
| // and 0xAD, 0x90 to [99834]. Decoding 2928 and 99834 individually won't reconstruct the original UTF-16 string '⭐' U-2B50; | ||
| // decoding all IDs together is required to get the expected result. |
There was a problem hiding this comment.
I could imagine someone wanting an API like IEnumerable<byte> Decode(IEnumerable<ids> ids, ...). Presumably if that was desired we could always add it in the future.
|
@stephentoub I have addressed all feedback, please let me know if you have any more feedback. Thanks! |
| @@ -233,7 +311,7 @@ private static (Dictionary<StringSpanOrdinalKey, int>?, Dictionary<int, string>? | |||
| /// <param name="text">The text to encode.</param> | |||
| /// <param name="isSpecialToken">Indicate if the token is a special token.</param> | |||
There was a problem hiding this comment.
Existing: what token does this refer to? The only other thing specified is text
There was a problem hiding this comment.
token is the string word. can be any word like dog or it can be special token like <|endoftext|>. I can change Indicate if the token is a special token. to Indicate if the text represent a special token. or similar.
There was a problem hiding this comment.
Is that the parameter text, and does that text need to represent a single token? Or does it refer to all tokens within text?
There was a problem hiding this comment.
the text can represent multiple tokens or represent one special token.
There was a problem hiding this comment.
Ok, so how does isSpecialToken apply to 'text` in the case it is multiple tokens?
There was a problem hiding this comment.
It is a flag telling if the input text is representing a special token or not so the encoder can treat it differently. Here is some example how this is used
There was a problem hiding this comment.
Ok, so we should probably refer to text in the docs.
Here's my attempt:
Indicates if the <paramRef name="text"/> in it's entirety is a special token. This method will throw if <paramRef name="isSpecialToken"/> is `true` and the specified <paramRef name="text"/> is not a special token.
Similarly it looks like the Count and EncodeToIds just return default values ignoring the text if it's not a special token so they could get a slightly different version of this.
I raised this issue because this parameter confused me when adopting the tokenizer.
There was a problem hiding this comment.
I'm curious as to the use case for setting isSpecialToken to true...?
There was a problem hiding this comment.
Seems like the only scenario is when someone wants to pass in a single special token string and get the value for that. If we're making them specify a parameter to this API to do that they might as well just call a different API to do it and avoid the confusing parameter on this API.
I wonder what happens if someone specifies a special token string but forgets to set isSpecialToken?
There was a problem hiding this comment.
@tarekgh and I talked about this offline - we'll update the docs for these methods in a separate PR and discuss this during API review.
| /// <exception cref="ArgumentNullException">The input text is null.</exception> | ||
| /// <exception cref="ArgumentOutOfRangeException">The maximum token count must be greater than 0.</exception> | ||
| /// <remarks> | ||
| /// If the tokenizer has a normalizer, the returned text will be the normalized text. Otherwise the returned text will be the input text. |
There was a problem hiding this comment.
Is it ever the case that someone might have pre-normalized text and want a method that doesn't do this normalization?
There was a problem hiding this comment.
Yes, when creating the tokenizer you have the option to provide the normalizer object. If you don't then the tokenizer will not do any normalization before processing the text.
There was a problem hiding this comment.
Just imagining that someone might want to call the normalizer once, then tell this method that they've already done the normalization and avoid double-normalization / allocation. My understanding of the use case for this API is to do a minimal amount of work so I was just asking myself "is there anything else that I can imagine someone might not want this method to do?" and normalization was the only thing I could imagine.
There was a problem hiding this comment.
Well written normalizer will return the original text without new allocation if there is no change from the original text. But I think processing time will be counted.
There was a problem hiding this comment.
Also, users can create a copy of the tokenizer without the normalization and can be used in such scenario too.
There was a problem hiding this comment.
Right, but I was more concerned with this API doing two things where someone might want it to do just one. It's the same feeling @stephentoub shared offline
The normalization stuff sneaking in here still rubs me the wrong way
I don't feel like it needs to be solved now, but it may be a topic during API review.
There was a problem hiding this comment.
The normalization is part of tokenization. It is optional for some scenario but important to other scenarios. So the API is not really doing two things more than communicating the encoding results including the change in the text. Anyway, I am open to any better suggestion that can make us avoid any confusion or to get cleaner API shape.
| @@ -177,7 +177,7 @@ private Bpe(Stream vocabStream, Stream? mergesStream, string? unknownToken, stri | |||
| /// Encode a text string to a list of tokens. | |||
| /// </summary> | |||
| /// <param name="text">The text to encode.</param> | |||
| /// <param name="isSpecialToken">Indicate if the token is a special token.</param> | |||
| /// <param name="isSpecialToken">Indicate if the text is a special token.</param> | |||
| /// <returns>The list of tokens generated from the text tokenization.</returns> | |||
| public override IReadOnlyList<Token> Encode(string text, bool isSpecialToken = false) | |||
There was a problem hiding this comment.
EncodeToIds takes a span but Encode takes a string. Is that ok? Are there places it'd be valuable for Encode to also take a span, or are there benefits to it being a string?
There was a problem hiding this comment.
IIRC we chatted about that before. Encode need to return tokens, if we pass ReadOnlySpan here we'll need to call ToString on it again. EncodeToIds doesn't need return tokens and that is why we are ok to use spans there. I am open to any suggestion if we have a better ideas.
There was a problem hiding this comment.
Hmm. Is that because we expect this text to frequently be a single token?
There was a problem hiding this comment.
Tokenizers using Regex to pre-tokenize and produces a smaller or partial words is possible to be a single token. So it depends on the pre-tokenization and the vocabulary of the tokenizer. You had another idea which we decided not go with but we can reconsider it which is passing both string and span. This can help in the future if we expose Span apis on Tokenizer class.
Fixes #7043
The change here is adding the following Tokenizer's APIs: