LanguageModel: append() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("Prompt API")}}{{SecureContext_Header}}
The **append()** method of the {{domxref("LanguageModel")}} interface adds content to the session's context window without generating a model response. It returns a {{jsxref("Promise")}} that resolves when the content has been successfully loaded into context. Use this method to preload a context before asking the model a question.
A context may be a document, conversation, history, or background information. You can call the append() method at any point during the session's lifetime.
Syntax
append(input)
append(input, options)Parameters
input- : The content to append to the context window. This is either:
- A string — Shorthand for a single textual message.
- An array of objects, each representing a single message in a conversation with a language model.
Objects may have the following properties:
role- : A string indicating the point of view the message is phrased from. Must be one of:
system- : A system-level instruction that guides the model's overall behavior. This must be the first instruction passed to the model.
user- : A message from the user, which the API should respond to.
assistant- : An input that provides context for the AI assistant, such as its persona or the format of its responses. Such messages mainly serve to provide context/history, and further shape how the model responds.
content- : A string representing a textual prompt, or an array of objects. Each object includes the following properties:
type- : An enumerated value representing the type of content. This can be one of:
audio- : Audio content.
image- : Image content.
text- : Textual content.
tool-call- : A tool invocation issued by the model.
tool-response- : The result of a tool invocation.
value- : The content of the message. If the
typeistext, this is always a string. If thetypeisaudioorimage, thevaluecan be one of several different object types; see What data types are accepted?. prefix{{optional_inline}}- : A boolean, defaulting to
false. Whentrue, the message is treated as a prefix for the model's next generated response rather than a complete turn. options{{optional_inline}}- : An object representing the options that can be passed. Properties include:
signal- : An {{domxref("AbortSignal")}} to cancel the append operation.
Return value
A {{jsxref("Promise")}} that resolves with undefined when the content has been prefilled into the context window, or rejects with one of the following exception values on failure.
Exceptions
AbortError{{domxref("DOMException")}}- : Thrown if the operation was canceled via the
signaloption. NotAllowedError{{domxref("DOMException")}}- : Thrown if usage of the method is blocked by a {{httpheader("Permissions-Policy/language-model", "language-model")}} {{httpheader("Permissions-Policy")}}.
NotSupportedError{{domxref("DOMException")}}- : Thrown if:
- A message's
roleisassistantand itstypeis anything other thantext. - A message's
typeistextand itsvalueis not a string. - The input or output text is in a language the user agent doesn't support for prompting.
- A message's
typeisimageoraudiobut the type was not listed inexpectedInputs, or thevalueis not an accepted data type. OperationError{{domxref("DOMException")}}- : Thrown if prefilling fails for any other reason not listed in the other exception types.
QuotaExceededError{{domxref("DOMException")}}- : Thrown if appending
inputwould cause the session's context usage to exceed the model's {{domxref("LanguageModel.contextWindow")}}. SyntaxError{{domxref("DOMException")}}- : Thrown if:
- No messages are included in the messages array.
- A message's
prefixproperty is set totrueand: - The message's
roleis notassistant. - The message is not the last item in the messages array.
- {{jsxref("TypeError")}}
- : Thrown if a message's
roleissystembut it was not the first message passed to the context.
Examples
See also Adding context with initial and ongoing prompt inputs > Appending extra messages to the context.
Append context before prompting
This example shows how to append to a context for the user role before calling prompt(). Note that we can just specify text input (documentText) in this case, because user is the default role.
const documentText = "This is my important essay...";
const session = await LanguageModel.create();
// Preload the document text into context
await session.append(documentText);
// Now ask questions about the document
const summary = await session.prompt(
"Summarize the key points of this document.",
);
console.log(summary);Appending context with an abort signal
An abort signal lets you cancel an append operation. The example below passes an {{domxref("AbortSignal")}} to the signal member and calls its abort() method after 3 seconds.
const controller = new AbortController();
setTimeout(() => controller.abort(), 3000);
try {
await session.append(
"Here is some background context for future questions.",
{
signal: controller.signal,
},
);
console.log("Context appended successfully.");
} catch (err) {
if (err.name === "AbortError") {
console.log("Append was aborted.");
}
}Checking context usage after appending
The code below shows how to log the number of tokens used after appending a large amount of context.
const largeDocument = "This is my large body of text...";
const session = await LanguageModel.create();
await session.append(largeDocument);
console.log(
`Context used: ${session.contextUsage} / ${session.contextWindow} tokens`,
);Specifications
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- {{domxref("LanguageModel.prompt()")}}
- {{domxref("LanguageModel.measureContextUsage()")}}
- Prompt API
- Using the Prompt API
- Adding context with initial and ongoing prompt inputs