תיעוד 35

מודלים מותאמים אישית

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

#מודלי ברירת מחדל

כברירת מחדל, Grok משתמש במודלים המתארחים על ידי SpaceXAI, והפעלות חדשות מתחילות עם grok-4.5. מודלי ברירת מחדל אינם דורשים הגדרה. בצע אימות באמצעות grok login או מפתח API, ולאחר מכן התחל הפעלה.

הצג את כל המודלים הזמינים:

grok models

#בחירת מודל

#דגל CLI

grok -p "Hello" -m grok-4.6

#פקודת סלאש

ב-TUI, החלף מודלים במהלך הפעלה:

/model grok-4.6

או השתמש בכינוי:

/m grok-4.6

#בורר מודלים (Ctrl+M)

לחץ על Ctrl+M מחלונית הגלילה לאחור כדי לפתוח את בורר המודלים. הוא מציג את כל המודלים הזמינים, הן מובנים והן מותאמים אישית, ומאפשר לך להחליף בלחיצת מקש אחת. כאשר המיקוד נמצא על שורת הפקודה, Ctrl+M מעביר לקלט מרובה שורות במקום זאת, השתמש ב-/model כדי להחליף בלי לעזוב את שורת הפקודה.

#רשימת היתרים לצי (`requirements.toml`)

מארחי Enterprise יכולים לקבע את קבוצת המודלים הניתנים לבחירה, לא רק את ברירת המחדל, בקובץ requirements.toml חתום. רשימה זו מחליפה כל allowed_models של המשתמש (אינה איחוד), כך ש-/model, Ctrl+M ו--m אינם יכולים להציע מודלים מחוצה לה.

[models]
default = "grok-4.5"
allowed_models = ["grok-4.5", "grok-4*"]

קיבוע צי תואם ל-model id (ולא למפתח קטלוג שנבחר על ידי המשתמש), כך שרשומת [model.<name>] מקומית אינה יכולה להרחיב את הקבוצה. הגדרת allowed_models בתצורת המשתמש עדיין מתאימה למפתח קטלוג או ל-model id. השמט את המפתח כדי להשאיר את תצורת המשתמש על כנה. מערך ריק הוא ללא הגבלה. קיבוע קיים אך בלתי קריא נסגר לכשל (שום דבר אינו ניתן לבחירה). ערך ברירת מחדל או ערך -m מחוץ לקבוצה המקובעת נדחה ברגע שקטלוג המודלים מאוחזר. פנה למנהל המערכת שלך, הרשימה אינה ניתנת לעריכה על ידי המשתמש.

#ברירת מחדל בקובץ התצורה

הגדר ברירת מחדל קבועה ב-~/.grok/config.toml:

[models]
default = "grok-4.5"

#ממשקי API נתמכים

Grok תומך בשלושה ממשקי API. הגדר את api_backend בתצורת [model.*] שלך כדי לבחור באיזה פרוטוקול המודל משתמש:

ערך	API	ברירת מחדל
`"chat_completions"`	OpenAI Chat Completions (`/v1/chat/completions`)	כן
`"responses"`	OpenAI Responses (`/v1/responses`)
`"messages"`	Anthropic Messages (`/v1/messages`)

כאשר אתה משמיט את api_backend, Grok משתמש ב-chat_completions.

כדי לשלוח כותרות אימות או גרסה ספציפיות לספק, למשל x-api-key של Anthropic, השתמש בשדה extra_headers המתואר להלן. Grok שולח כותרות אלו כלשונן בכל בקשה לנקודת הקצה.

#הגדרת מודלים מותאמים אישית

הוסף נקודות קצה של מודלים מותאמים אישית ב-~/.grok/config.toml תחת מקטעי [model.<name>]:

[model.my-model]
model = "model-id"                        
# מזהה מודל שנשלח ל-API
base_url = "https://api.example.com/v1"   
# נקודת קצה תואמת OpenAI
name = "Display Name"                     
# מוצג בבורר המודלים
description = "Model description"          
# תיאור אופציונלי
api_key = "sk-..."                        
# מפתח API עבור ספק זה (אופציונלי)
env_key = "XAI_API_KEY"                   
# משתנה סביבה המחזיק את מפתח ה-API (אופציונלי; מחרוזת או מערך)
api_backend = "chat_completions"          
# "chat_completions", "responses", או "messages"
reasoning_summary = "concise"             
# Responses API בלבד: "none", "auto", "concise", או "detailed"
temperature = 0.7                         
# טמפרטורת דגימה
top_p = 0.95                              
# פרמטר דגימת גרעין (Nucleus sampling)
max_completion_tokens = 8192              
# מספר אסימונים מרבי לכל תגובה
context_window = 128000                   
# סך כל חלון ההקשר באסימונים
extra_headers = { "x-api-key" = "sk-..." } 
# כותרות בקשה נוספות, נשלחות כלשונן (אופציונלי)
query_params = { api-version = "2026-07-22" } 
# פרמטרי שאילתה המצורפים לכל כתובת URL של בקשה (אופציונלי)
env_http_headers = { "X-Tenant" = "TENANT_TOKEN" }    
# כותרות ממשתני סביבה, מפוענחות בעת בניית הלקוח (אופציונלי)

#פענוח פרטי אימות

Grok מפענח את מפתח ה-API לפי הסדר הבא:

השדה api_key בתצורת המודל
משתנה או משתני הסביבה המוגדרים על ידי env_key, מחרוזת בודדת או מערך של שמות. הערך המוגדר הראשון שאינו ריק מנצח (לדוגמה env_key = ["ANTHROPIC_AUTH_TOKEN", "LC_ANTHROPIC_AUTH_TOKEN"] עבור העברת LC_* ב-SSH)
אסימון ההפעלה המחובר שלך (מתוך grok login), עבור מודל ללא api_key או env_key משלו
משתנה הסביבה XAI_API_KEY (ברירת מחדל גלובלית לגיבוי; Grok מקבל גם את GROK_CODE_XAI_API_KEY לצורך תאימות לאחור)

#חלון הקשר

הערך context_window מורה ל-Grok מתי להפעיל דחיסה אוטומטית. כאשר אתה עוקף מודל מוכר, Grok יורש את חלון ההקשר של אותו מודל. כאשר אתה מגדיר מודל חדש ומשמיט את context_window, ברירת המחדל של Grok היא 200,000 אסימונים, לכן הגדר אותו במפורש כדי להתאים לספק שלך.

#כותרות ברירת מחדל גלובליות

כדי להחיל את אותן הכותרות על כל מודל בקטלוג, מובנה, כזה שאוחזר מראש מ-/v1/models, או מותאם אישית, הגדר אותן פעם אחת תחת המקטע הגלובלי [models] במקום לחזור עליהן עבור כל מודל:

[models]
extra_headers = { "X-Request-Tags" = "team=example,env=prod" }

אלו פועלות כבסיס עבור בקשות ההיסק של כל מודל. רשומת [model.<id>].extra_headers ברמת המודל עוקפת את ברירת המחדל הגלובלית לפי מפתח (התאמה שאינה רגישה לאותיות גדולות או קטנות): מפתח המוגדר במודל מנצח, בעוד שכל המפתחות הגלובליים בלבד עדיין עוברים בירושה לאותו מודל. בדומה לשדה ברמת המודל, הן נלוות לקריאות ההיסק של אותו מודל, ולא לשירותים נפרדים כגון יצירת תמונות או יצירת וידאו, מה שהופך אותן לשימושיות עבור תגי שיוך (לדוגמה, מעקב עלויות) מבלי להגדיר אותן מחדש בכל פעם שמודל חדש מופיע.

#ערכי ברירת מחדל גלובליים

ניתן להגדיר כמה הגדרות נפוצות ברמת המודל פעם אחת תחת [models] כברירת מחדל עבור כל מודל. ערך [model.<id>] ברמת המודל תמיד מנצח; הערך הגלובלי ממלא רק את המקומות שבהם מודל (או רשימת המודלים של השרת) השאיר את השדה ללא הגדרה:

[models]
temperature                 = 0.7
top_p                       = 0.95
max_completion_tokens       = 8192
max_retries                 = 8
rate_limit_retry_threshold  = 4
inference_idle_timeout_secs = 600
subagent_rate_limit_max_attempts = 8
stream_tool_calls           = true

זוהי קבוצה קטנה וקבועה של בוררים לכלל הסביבה. הגדרות המזהות מודל ספציפי (model, base_url, api_key, context_window, ...) אינן יכולות לקבל ברירת מחדל בדרך זו, וכמה הגדרות בעלות תצורה ייעודית משלהן, דחיסה אוטומטית ([session]), תווית הנחיית המערכת ([agent]), ומאמץ הסקה ([models].default_reasoning_effort), נשארות במיקומן הקיים.

rate_limit_retry_threshold ו-subagent_rate_limit_max_attempts בוחרים נתיבי ניסיון חוזר שונים של שגיאות 429 עבור תתי סוכנים. הגדרת rate_limit_retry_threshold גורמת לדוגם להיות הבעלים של אותם ניסיונות חוזרים ומבטלת את לולאת ההמתנה הנפרדת של תת הסוכן, כולל תקציב ההמתנה המצטבר שלה של 150 שניות וטלמטריית ההמתנה. subagent_rate_limit_max_attempts חל רק כאשר סף הדוגם אינו מוגדר.

הערה לגבי stream_tool_calls: הגדרה זו משפיעה על מבנה הבקשה, ולא רק על הדגימה. כמה נקודות קצה (ספקי BYOK מסוימים) מצפות שהיא תישאר ללא הגדרה; אם הגדרה גלובלית של stream_tool_calls = true גורמת לבעיות עבור מודל כזה, בטל אותה עבור אותו מודל באמצעות stream_tool_calls = false בבלוק ה-[model.<id>] שלו.

#פרמטרי שאילתה של הבקשה

שערי גישה מסוימים מבצעים ניתוב או קביעת גרסה לפי מחרוזת השאילתה. query_params מצרף פרמטרי שאילתה מקודדי אחוזים לכל בקשה ש-Grok מבצע עבור מודל. לדוגמה, שער גישה שבוחר גרסת API בדרך זו:

[model.my-gateway]
model = "my-model"
base_url = "https://gateway.example/v1"
api_backend = "responses"
env_key = "GATEWAY_API_KEY"
query_params = { api-version = "2026-07-22" }

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

#כותרות ממשתני סביבה

env_http_headers ממפה כותרת בקשה לשם של משתנה סביבה שמספק את הערך שלה, כך שסוד הנדרש בכל בקשה לעולם אינו צריך להיכתב אל config.toml:

[model.gateway]
model = "my-model"
base_url = "https://gateway.example/v1"
env_http_headers = { "X-Tenant-Token" = "GATEWAY_TENANT_TOKEN" }

Grok קורא כל משתנה כאשר הוא בונה את הלקוח עבור הפעלה ומציב את הערך בכותרות הבקשה בלבד, לעולם לא בדיסק. דילוג על כותרת מתבצע כאשר המשתנה שלה אינו מוגדר או ריק, וערך מפוענח עוקף רשומת extra_headers בעלת אותו שם. השתמש ב-extra_headers עבור ערך סטטי וב-env_http_headers עבור ערך שמגיע מהסביבה.

שני השדות פועלים גם בבלוק משותף של [model_providers.<id>]. מודל שמצביע על ספק באמצעות model_provider = "<id>" יורש את ה-query_params וה-env_http_headers של הספק כאשר אינו מגדיר כאלה משלו, בהתאמה לאופן שבו extra_headers עובר בירושה.

#עקיפת מודלים מובנים

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

# עקיפת מפתח ה-API בלבד עבור מודל ברירת מחדל
[model.grok-4.6]
api_key = "my-api-key"

# עקיפת טמפרטורה והוספת מפתח API מותאם אישית
[model.grok-4.6]
temperature = 0.5
api_key = "sk-custom"

כאשר אתה עוקף מודל מובנה, Grok מתחיל עם תצורת ברירת המחדל (כולל ה-base_url הנכון), ולאחר מכן מחיל רק את השדות שציינת. שדות שלא צוינו יורשים את ערכם מברירת המחדל.

#סדר עדיפויות

התצורה שלך ([model.*]), העדיפות הגבוהה ביותר
מודלים שאוחזרו מראש מ-/v1/models מרוחק
ערכי ברירת מחדל מוטמעים בקוד, העדיפות הנמוכה ביותר

#דוגמאות לספקים

#Anthropic (Claude)

השתמש במודלי Claude ישירות דרך ה-Anthropic Messages API:

[model.claude-opus]
model = "claude-opus-4-6"
base_url = "https://api.anthropic.com/v1"
name = "Claude Opus 4.6"
api_backend = "messages"
context_window = 200000
extra_headers = { "x-api-key" = "sk-ant-...", "anthropic-version" = "2023-06-01" }

ממשק הקצה messages משתמש בפרוטוקול Anthropic Messages. חברת Anthropic מבצעת אימות באמצעות כותרת x-api-key ולא באמצעות Authorization: Bearer, לכן העבר את המפתח שלך דרך extra_headers, ש-Grok שולח כלשונו.

#OpenAI (Chat Completions)

[model.gpt-4o]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
name = "GPT-4o"
env_key = "OPENAI_API_KEY"

ברירת המחדל של api_backend היא "chat_completions", כך שאינך צריך להגדיר אותו במפורש עבור OpenAI.

#OpenAI (Responses API)

אם הספק שלך תומך ב-Responses API החדש יותר:

[model.gpt-4o-responses]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
name = "GPT-4o (Responses)"
api_backend = "responses"
env_key = "OPENAI_API_KEY"

ב-Responses API, כברירת מחדל Grok מבקש סיכום הסקה מסוג concise; זהו המקור של טקסט ההסקה המוצג בממשק המשתמש. reasoning_summary משנה את הבקשה: detailed או auto עבור סיכום מלא יותר, או none כדי להשמיט את השדה עבור שערי גישה שדוחים אותו.

#AWS Bedrock (Mantle)

שער הגישה התואם ל-OpenAI של Bedrock דוחה את reasoning.summary, לכן הגדר reasoning_summary = "none". הוא מבצע אימות באמצעות מפתח API של Bedrock כאסימון bearer; הדוגמה להלן מנפיקה אסימון קצר מועד דרך ספק אימות בעל שם:

[auth_provider.bedrock]
command = "aws-bedrock-token"   
# מדפיס מפתח API של Bedrock ל-stdout (למשל דרך aws-bedrock-token-generator)
token_ttl_secs = 3600

[model."bedrock-grok-4.6"]
model = "xai.grok-4.6"
base_url = "https://bedrock-mantle.us-west-2.api.aws/openai/v1"
name = "Grok 4.6 (Bedrock)"
api_backend = "responses"
reasoning_summary = "none"
auth_provider = "bedrock"
context_window = 500000

#Ollama (מודלים מקומיים)

הפעל מודלים באופן מקומי באמצעות Ollama:

[model.ollama-codellama]
model = "codellama"
base_url = "http://localhost:11434/v1"
name = "CodeLlama (Ollama)"

ודא ש-Ollama פועל (ollama serve) ושהמודל נמשך (ollama pull codellama).

#Together AI

[model.together-mixtral]
model = "mistralai/Mixtral-8x7B-Instruct-v0.1"
base_url = "https://api.together.xyz/v1"
name = "Mixtral 8x7B"
env_key = "TOGETHER_API_KEY"

#שרת מקומי תואם OpenAI

כל שרת שמממש את OpenAI Chat Completions או Responses API:

[model.local-llama]
model = "llama-3.1-70b"
base_url = "http://localhost:8080/v1"
name = "Local Llama"
temperature = 0.8

#נקודת קצה של מודלים מותאמים אישית

כוון את Grok לנקודת קצה מותאמת אישית של /v1/models התואמת ל-OpenAI במקום ברירת המחדל. השתמש באפשרות זו כאשר המודלים שלך נמצאים מאחורי שער גישה ארגוני או שירות היסק באירוח עצמי.

#משתני סביבה

משתנה	נדרש	תיאור
`GROK_MODELS_BASE_URL`	כן	כתובת Base URL עבור היסק. Grok מאחזר את רשימת המודלים מ-`{base_url}/models`.
`XAI_API_KEY`	כן	מפתח API שנשלח כ-`Authorization: Bearer`. Grok מקבל גם את `GROK_CODE_XAI_API_KEY`.
`GROK_MODELS_LIST_URL`	לא	עקיפת כתובת ה-URL של רשימת המודלים כאשר היא שונה מ-`{base_url}/models`.

#הגדרה

export GROK_MODELS_BASE_URL="https://api.acme.com/v1"
export XAI_API_KEY="xai-..."
grok

#חלופה באמצעות קובץ תצורה

[endpoints]
models_base_url = "https://api.acme.com/v1"

# עקיפת מפתח ה-API בלבד עבור מודל ספציפי
[model.grok-4.6]
api_key = "my-api-key"

כאשר אתה משתמש ב-[endpoints] עם עקיפות חלקיות של מודל, Grok יורש את ה-base_url מתצורת נקודות הקצה, כך שאינך צריך לציין אותו בכל מקטע [model.*].

#התנהגות אימות

כאשר אתה מגדיר את models_base_url, Grok משתמש באימות מפתח API (Authorization: Bearer) במקום באימות הפעלה. אינך זקוק ל-grok login, מפתח ה-API מספיק.

#מודל חיפוש באינטרנט

הכלי web_search משתמש במודל נפרד. הגדר אותו באמצעות:

[models]
web_search = "grok-4.5"

או באמצעות משתנה סביבה:

export GROK_WEB_SEARCH_MODEL="grok-4.5"

אם אתה מכוון את חיפוש האינטרנט למודל מותאם אישית, אתה זקוק גם לרשומת [model.*] כדי ש-Grok יוכל לגשת אליו. חיפוש אינטרנט בצד השרת ("backend") פועל רק כאשר המודל מגדיר supports_backend_search = true (והגרסה הבנויה מאפשרת חיפוש backend); הדבר אינו תלוי ב-api_backend:

[models]
web_search = "my-custom-model"

[model.my-custom-model]
model = "my-custom-model"
supports_backend_search = true

#שימוש במודלים מותאמים אישית

# הצגת מודלים זמינים (כולל מותאמים אישית)
grok models

# שימוש ב-TUI באמצעות פקודת סלאש
/model my-model

# שימוש במצב headless
grok -p "Hello" -m my-model

# הגדרה כברירת מחדל ב-config.toml:
[models]
default = "my-model"

#פריסה ארגונית

תצורה מלאה עבור פריסה ארגונית עם מודלים מותאמים אישית:

[cli]
auto_update = false

[auth]
auth_provider_command = "/usr/local/bin/my-company-auth-provider"
auth_provider_label = "Acme Corp"
auth_token_ttl = 3600

[models]
default = "company-grok"

[model.company-grok]
model = "grok-4.6"
base_url = "https://grok-proxy.acme.com/"
name = "Grok 4.6 (Proxy)"
context_window = 128000

[features]
telemetry = false

#פתרון בעיות

#מודל לא נמצא

# הצגת מודלים זמינים
grok models

# בדיקת שגיאות הקלדה במקטעי [model.*] ב-config.toml

#שגיאות חיבור

ודא שנקודת הקצה נגישה:

curl -s https://api.example.com/v1/models \
  -H "Authorization: Bearer $XAI_API_KEY"

#רישום יומנים לניפוי שגיאות

RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok
tail -f /tmp/grok.log

חפש רשומות יומן המכילות model או sampling כדי לעקוב אחר בחירת מודל וקריאות API.