המדיניות PromptTokenLimit

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

אפשר לעיין במסמכי העזרה של Apigee Edge.

סקירה כללית

המדיניות PromptTokenLimit מגינה על הקצה העורפי של מודל שפה גדול (LLM) מפני עומסי תנועה, על ידי הגבלת מספר הטוקנים בהנחיות של המשתמשים.

המדיניות PromptTokenLimit דומה למדיניות SpikeArrest, אבל המדיניות SpikeArrest מגבילה את מספר הבקשות, ואילו המדיניות PromptTokenLimit מגבילה את מספר הטוקנים בבקשות האלה. המדיניות הזו מיועדת במיוחד לאפליקציות LLM שבהן העלות והביצועים קשורים באופן ישיר למספר הטוקנים שעוברים עיבוד.

המדיניות הזו היא מדיניות ניתנת להרחבה, והשימוש בה עשוי להשפיע על העלות או על הניצול, בהתאם לרישיון Apigee שלכם. למידע על סוגי המדיניות וההשלכות של השימוש בהם, קראו את המאמר סוגי מדיניות.

ההבדל בין PromptTokenLimit לבין LLMTokenQuota

המדיניות PromptTokenLimit משמשת לניהול תנועה תפעולית כדי למנוע עליות חדות פתאומיות בשימוש בטוקנים. לעומת זאת, המדיניות LLMTokenQuota משמשת לאכיפת מגבלות צריכה באפליקציות לקוח לאורך תקופות ארוכות יותר (כמו שעות, ימים או חודשים) כדי לנהל את העלויות ולאכוף הסכמים עסקיים.

רכיב PromptTokenLimit

מגדירה את המדיניות PromptTokenLimit.

ערך ברירת המחדל מידע נוסף מופיע בקטע הכרטיסייה "מדיניות ברירת המחדל" שבהמשך.
חובה? אופציונלי
סוג אובייקט מורכב
רכיב הורה לא רלוונטי
רכיבי צאצא <Identifier>
<Rate> (חובה)
<UseEffectiveCount>
<UserPromptSource>
<IgnoreUnresolvedVariables>

תחביר

הרכיב PromptTokenLimit משתמש בתחביר הבא:

<PromptTokenLimit continueOnError="false" enabled="true" name="POLICY_NAME">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

מדיניות ברירת המחדל

בדוגמה הבאה מוצגות הגדרות ברירת המחדל כשמוסיפים מדיניות PromptTokenLimit לתהליך בממשק המשתמש:

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

דוגמאות

הדוגמאות הבאות ממחישות כמה מהדרכים שבהן אפשר להשתמש במדיניות PromptTokenLimit:

דוגמה 1

הגבלת אסימוני הנחיה ברפליקה אחת.

בדוגמה הזו, הגבלת טוקנים של פרומפט מתרחשת בתוך רפליקה יחידה ולא מופצת בין כמה מעבדי הודעות באזור. 

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

דוגמה 2

הגבלת טוקנים מבוזרת.

בדוגמה הזו, הגבלת הטוקנים של ההנחיות מפוזרת בין כמה רפליקות באזור, ונעשה שימוש באלגוריתם להגבלת קצב של יצירת בקשות מסוג "חלון הזזה".

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

דוגמה 3

הגבלת מספר הטוקנים לכל בקשה בהתאם לגודל חלון ההקשר.

בדוגמה הזו, הגבלת הטוקנים של הפרומפט מתרחשת בתוך רפליקה יחידה ולא מופצת בין כמה מעבדי הודעות באזור. ההגדרה הספציפית הזו משמשת להגבלת מספר הטוקנים לכל בקשה בגודל חלון ההקשר.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.messages',request.content,true)}</UserPromptSource>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

דוגמה 4

הגבלת טוקנים מבוזרת עם ערכי ברירת מחדל.

בדוגמה הזו, הגבלת הטוקנים של ההנחיות מתרחשת ברפליקה אחת ולא מופצת בין כמה מעבדי בקשות באזור. נעשה שימוש בערך ברירת המחדל של מקור ההנחיה למשתמש: {jsonPath('$.messages',request.content,true)} 

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הצאצא של <PromptTokenLimit>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<Identifier>

מאפשרת לבחור איך לקבץ את הבקשות כדי שאפשר יהיה להחיל את המדיניות PromptTokenLimit על סמך הלקוח. לדוגמה, אפשר לקבץ בקשות לפי מזהה מפתח, ובמקרה כזה הבקשות של כל מפתח ייספרו במסגרת מגבלת PromptTokenLimit שלו, ולא כל הבקשות לשרת ה-proxy.

אם משאירים את הרכיב <Identifier> ריק, מגבלת קצב אחת נאכפת על כל הבקשות ל-API proxy הזה.

ערך ברירת מחדל לא רלוונטי
חובה? אופציונלי
סוג String
רכיב הורה <PromptTokenLimit>
רכיבי צאצא ללא

תחביר

<PromptTokenLimit
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="POLICY_NAME"
>
  <Identifier ref="FLOW_VARIABLE"/>
</PromptTokenLimit>

דוגמה 1

בדוגמה הבאה, המדיניות PromptTokenLimit חלה על כל מזהה מפתח:

<PromptTokenLimit name="PTL-limitTokens-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

בטבלה הבאה מתוארים המאפיינים של <Identifier>:

מאפיין תיאור ברירת מחדל נוכחות
ref מזהה את המשתנה שלפיו PromptTokenLimit מקבץ בקשות נכנסות. אפשר להשתמש בכל משתנה זרימה כדי לציין לקוח ייחודי, כמו אלה שזמינים עם מדיניות VerifyAPIKey. אפשר גם להגדיר משתנים בהתאמה אישית באמצעות מדיניות JavaScript או מדיניות AssignMessage. לא רלוונטי חובה

<Rate>

מציינת את הקצב שבו מגבילים את העליות החדות (או הזינוקים) בטוקנים, על ידי הגדרת מספר הטוקנים שמותרים במרווחים של דקה או שנייה. אפשר להשתמש ברכיב הזה בשילוב עם <Identifier> כדי לווסת את התנועה בצורה חלקה בזמן הריצה על ידי קבלת ערכים מהלקוח. משתמשים ברכיב <UseEffectiveCount> כדי להגדיר את אלגוריתם הגבלת קצב של יצירת בקשות שבו נעשה שימוש במדיניות.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג מספר שלם
רכיב הורה <PromptTokenLimit>
רכיבי צאצא ללא

תחביר

אפשר לציין תעריפים באחת מהדרכים הבאות:

  • תעריף קבוע שאתם מציינים בגוף הרכיב <Rate>
  • ערך משתנה, שאפשר להעביר על ידי הלקוח; מזהים את שם משתנה הזרימה באמצעות המאפיין ref
<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

ערכי שיעור תקינים (מוגדרים כערך משתנה או בגוף הרכיב) צריכים להיות בפורמט הבא:

  • ‫intps (מספר הטוקנים לשנייה, מוחלק למרווחי זמן של אלפיות השנייה)
  • ‫intpm (מספר הטוקנים לדקה, מוחלק למרווחים של שניות)

הערך של int חייב להיות מספר שלם חיובי שאינו אפס.

דוגמה 1

בדוגמה הבאה, הקצב מוגדר ל-5 אסימונים לשנייה:

<PromptTokenLimit name="PTL-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

המדיניות מחליקה את הקצב לאסימון אחד שמותר כל 200 אלפיות השנייה (1000/5).

דוגמה 2

בדוגמה הבאה, הקצב מוגדר ל-12 אסימונים לדקה:

<PromptTokenLimit name="PTL-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

המדיניות לדוגמה הזו מחליקה את הקצב לאסימון אחד שמותר כל חמש שניות (60/12).

בטבלה הבאה מתוארים המאפיינים של <Rate>:

מאפיין תיאור נוכחות ברירת מחדל
ref מזהה משתנה זרימה שמציין את הקצב. יכול להיות שזה יהיה משתנה של זרימת נתונים, כמו פרמטר של שאילתת HTTP, כותרת או תוכן של גוף ההודעה, או ערך כמו KVM. מידע נוסף זמין במאמר חומר עזר בנושא משתני זרימה.

אפשר גם להשתמש במשתנים מותאמים אישית באמצעות מדיניות JavaScript או מדיניות AssignMessage.

אם מגדירים גם את ref וגם את גוף הרכיב הזה, הערך של ref מוחל ומקבל עדיפות כשהמשתנה של התהליך מוגדר בבקשה. (ההפך הוא הנכון כשהמשתנה שזוהה ב-ref לא מוגדר בבקשה).

לדוגמה:

<Rate ref="request.header.custom_rate">1pm</Rate>

בדוגמה הזו, אם הלקוח לא מעביר כותרת custom_rate, אז הקצב של ה-proxy ל-API הוא טוקן אחד לדקה לכל הלקוחות. אם הלקוח מעביר כותרת custom_rate שהערך שלה הוא 10ps, לכל הלקוחות בשרת ה-proxy – עד שנשלחת בקשה בלי הכותרת custom_rate.

אפשר להשתמש ב-<Identifier> כדי לקבץ בקשות ולאכוף תעריפים מותאמים אישית לסוגים שונים של לקוחות.

אם מציינים ערך ל-ref אבל לא מגדירים את הקצב בגוף של הרכיב <Rate> והלקוח לא מעביר ערך, המדיניות PromptTokenLimit מחזירה שגיאה.

 אופציונלי לא רלוונטי
בטבלה הבאה מפורטים המאפיינים של Rate שמגדירים את ההתנהגות של הגבלת התנועה:
מאפיין תיאור
messagesPerPeriod מציין את מספר האסימונים המותרים בפרק זמן מוגדר. לדוגמה, אם מדיניות מוגדרת ל-'10ps' (10 אסימונים לשנייה), הערך של messagesPerPeriod יהיה 10.
periodInMicroseconds מגדירה את התקופה, במיקרו-שניות, שבה מחושב הערך של messagesPerPeriod. בהגדרה של "10ps", הערך הזה יהיה 1,000,000, ששווה לשנייה אחת.
maxBurstMessageCount מייצג את המספר המקסימלי של טוקנים שאפשר לאפשר באופן מיידי או בפרק זמן קצר בתחילת מרווח חדש.

<UseEffectiveCount>

האלמנט הזה מאפשר לכם לבחור בין אלגוריתמים שונים של PromptTokenLimit על ידי הגדרת הערך ל-true או ל-false, כמו שמוסבר בהמשך:

TRUE

אם המדיניות מוגדרת לערך true, המגבלה PromptTokenLimit מופצת באזור. המשמעות היא שספירת הבקשות מסונכרנת בין מעבדי ההודעות (MP) באזור. בנוסף, נעשה שימוש באלגוריתם של הגבלת קצב של יצירת בקשות מסוג 'חלון נע'. האלגוריתם הזה מספק התנהגות עקבית של הגבלת קצב של יצירת בקשות, ולא "מחליק" את מספר הבקשות הנכנסות שאפשר לשלוח לקצה העורפי. אם נשלח פרץ של בקשות בפרק זמן קצר, הן מותרות כל עוד הן לא חורגות ממגבלת הקצב שהוגדרה ברכיב <Rate>. לדוגמה:

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

false (ברירת מחדל)

אם המדיניות מוגדרת ל-false (ברירת המחדל), היא משתמשת באלגוריתם של token bucket כדי להחלק את העליות החדות בשימוש באסימונים. האלגוריתם מחלק את מגבלת הקצב שאתם מציינים למרווחים קטנים יותר. החיסרון בגישה הזו הוא שאסימונים לגיטימיים רבים שמגיעים בפרק זמן קצר עלולים להידחות.

לדוגמה, נניח שהזנתם קצב של 30pm (30 טוקנים לדקה). בבדיקות, יכול להיות שתחשבו שאתם יכולים לשלוח 30 טוקנים בשנייה אחת, כל עוד הם מגיעים תוך דקה. אבל זה לא האופן שבו המדיניות אוכפת את ההגדרה. אם חושבים על זה, 30 טוקנים בשנייה אחת יכולים להיחשב כעלייה קטנה בסביבות מסוימות.

  • התעריפים לדקה מוחלקים לבקשות מלאות שמותרות במרווחים של שניות.

    לדוגמה, אם מגדירים 30pm, ההחלקה תתבצע כך:
    60 שניות (דקה אחת) / 30pm = אינטרוולים של 2 שניות, או טוקן אחד מותר כל 2 שניות. אם תשלחו טוקן שני תוך 2 שניות, הוא ייכשל. בנוסף, אם תנסו להשתמש בטוקן ה-31 בתוך דקה, הפעולה תיכשל.

  • שיעורים של לשנייה מוחלקים לבקשות מלאות שמותרות במרווחי זמן של אלפיות השנייה.

    לדוגמה, אם המהירות היא 10ps, ההחלקה תתבצע כך:
    1,000 מילישניות (1 שנייה) חלקי 10ps = מרווחים של 100 מילישניות, או טוקן אחד מותר כל 100 מילישניות. אם תנסו ליצור טוקן שני בתוך 100 אלפיות השנייה, הפעולה תיכשל. בנוסף, אם תנסו להנפיק אסימון 11 בתוך שנייה, הפעולה תיכשל.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב הורה <PromptTokenLimit>
רכיבי צאצא ללא

בטבלה הבאה מתוארים המאפיינים של הרכיב <UseEffectiveCount>:

מאפיין תיאור ברירת מחדל נוכחות
ref מזהה את המשתנה שמכיל את הערך של <UseEffectiveCount>. זה יכול להיות כל משתנה זרימה, כמו פרמטר של שאילתת HTTP, כותרת או תוכן של גוף ההודעה. מידע נוסף זמין במאמר חומר עזר בנושא משתני זרימה. אפשר גם להגדיר משתנים בהתאמה אישית באמצעות מדיניות JavaScript או מדיניות AssignMessage. לא רלוונטי אופציונלי

<UserPromptSource>

המקור לאחזור טקסט של הנחיה למשתמש. שימוש ב תבנית הודעה.

תבנית ההודעה צריכה לספק ערך יחיד של טקסט הפרומפט של המשתמש.

לדוגמה, {jsonPath('$.contents[-1].parts[-1].text',request.content,true)}.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג String
רכיב הורה <PromptTokenLimit>
רכיבי צאצא ללא

תחביר

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

דוגמה 1

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

<IgnoreUnresolvedVariables>

ההגדרה הזו קובעת אם העיבוד ייפסק כשהמערכת תיתקל במשתנה לא פתור.

הערך true מאפשר להתעלם ממשתנים שלא נפתרו ולהמשיך בעיבוד. אחרת false. ערך ברירת המחדל הוא false.

ערך ברירת המחדל לא נכון
חובה? אופציונלי
סוג בוליאני
רכיב הורה <PromptTokenLimit>
רכיבי צאצא ללא

תחביר

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

דוגמה

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>10ps</Rate>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PromptTokenLimit>

משתני זרימה

כשמדיניות PromptTokenLimit מופעלת, משתני הזרימה הבאים מאוכלסים:

משתנה סוג הרשאה תיאור
ratelimit.POLICY_NAME.failed בוליאני הרשאת קריאה בלבד המשתנה הזה הוא true אם הייתה שגיאת ביצוע פנימית במדיניות. אין להשתמש במשתנה הזה כדי לבדוק אם חרגתם ממגבלת הקצב. יכול להיות שהיא מוגדרת ל-true בעומס גבוה בגלל העיצוב של המדיניות, שמאפשר גישה במקרה של כשל.
ratelimit.POLICY_NAME.resolvedUserPrompt String קריאה בלבד הפונקציה מחזירה את ההנחיה שחולצה מהמשתמש.
ratelimit.POLICY_NAME.userPromptSource String הרשאת קריאה בלבד הפונקציה מחזירה את תבנית ההודעה לפרומפט של המשתמש שצוין במדיניות.
ratelimit.POLICY_NAME.userPromptTokenCount String קריאה בלבד הפונקציה מחזירה את מספר הטוקנים של הנחיית המשתמש שחולצה.

מידע נוסף זמין במאמר חומר עזר בנושא משתני זרימה.

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. You may also see SpikeArrest policy errors. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Apigee fault Cause Fix
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSE Unable to extract the user prompt from the API request.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSE PromptTokenLimit violation.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 TRUE Tokens cannot be calculated for the user prompt.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault code HTTP status Apigee fault Cause Fix
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSE MessageWeight is not supported for the PromptTokenLimit policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
ratelimit.policy_name.fault.name fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. ratelimit.PTL-PromptTokenLimitPolicy.failed = true

Example error response

Shown below is an example error response:

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.prompttokenlimit.PromptTokenLimitViolation"
      },
      "faultstring":"Prompt Token Limit Violation. Allowed rate : MessageRate{capacity=10, period=Minutes}"
   }
}

Example fault rule

Shown below is an example fault rule to handle a PromptTokenLimitViolation fault:

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>Assign-Message-1</Name>
        </Step>
        <Condition>(fault.name Matches "PromptTokenLimitViolation")</Condition>
    </FaultRule>
</FaultRules>

קוד הסטטוס הנוכחי של HTTP לחריגה ממגבלת הקצב שנקבעה על ידי מדיניות LLMTokenQuota או PromptTokenLimit הוא 429 (יותר מדי בקשות).

סכימות

כל סוג מדיניות מוגדר על ידי סכימת XML‏ (.xsd). סכימות המדיניות זמינות ב-GitHub.

נושאים קשורים