LangChain — ئۇيغۇرچە تولۇق يىلنامە

# ئاساسلىق ئورنىتىش 
pip install langchain langchain-core langchain-community

 # LLM مۇلازىمەت بىرلەشتۈرمىلىرى 
pip install langchain-openai        # OpenAI / Azure 
pip install langchain-anthropic     # Claude 
pip install langchain-google-genai  # Gemini 
pip install langchain-ollama        # يەرلىك LLM 

 # RAG ئۈچۈن 
pip install langchain-chroma        # Chroma Vector DB 
pip install faiss-cpu               # FAISS 
pip install sentence-transformers   # Embedding 

 # LangGraph 
pip install langgraph

 # .env ھۆججىتى 
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LANGCHAIN_API_KEY=ls__...      # LangSmith (كۆزىتىش) 
LANGCHAIN_TRACING_V2=true

# ── OpenAI ─────────────────────────────────────────────── 
 from   langchain_openai   import   ChatOpenAI 

 gpt  =  ChatOpenAI (
    model       =  "gpt-4o" ,
    temperature =  0.7 ,        # 0=جامع، 2=ئىجادىيچان 
    max_tokens  =  2048 ,
)

 # ── Anthropic Claude ───────────────────────────────────── 
 from   langchain_anthropic   import   ChatAnthropic 

 claude  =  ChatAnthropic (
    model       =  "claude-sonnet-4-6" ,
    temperature =  0 ,
    max_tokens  =  4096 ,
)

 # ── Google Gemini ───────────────────────────────────────── 
 from   langchain_google_genai   import   ChatGoogleGenerativeAI 

 gemini  =  ChatGoogleGenerativeAI (
    model =  "gemini-2.0-flash" ,
)

 # ── Ollama (يەرلىك ھەقسىز) ─────────────────────────────── 
 from   langchain_ollama   import   ChatOllama 

 llama  =  ChatOllama (model= "llama3.1:8b" )   # ollama run llama3.1 

 # ── بىرلىككە كەلتۈرۈلگەن چاقىرىش ──────────────────────── 
 from   langchain_core.messages   import   HumanMessage ,  SystemMessage 

 messages  = [
     SystemMessage (content= "سەن ئۇيغۇرچە ياردەمچىسەن." ),
     HumanMessage (content= "LangChain نىمە ئۈچۈن ئىشلىتىلىدۇ؟" ),
]

 response  =  claude . invoke ( messages )
 print ( response .content)          # AIMessage.content 
 print ( response .usage_metadata)    # تامغا ئىشلىتىش

from   langchain_core.prompts   import  (
     PromptTemplate ,
     ChatPromptTemplate ,
     FewShotPromptTemplate ,
     MessagesPlaceholder ,
)

 # ── 1. PromptTemplate (ئاددىي تولدۇرۇش) ───────────────── 
 pt  =  PromptTemplate (
    input_variables = [ "ئىشلەتكۈچى" ,  "سوئال" ],
    template =  "{ئىشلەتكۈچى} نىڭ سوئالى: {سوئال}\nجاۋاپ:" 
)
 print ( pt . format (ئىشلەتكۈچى= "Idirak" , سوئال= "RAG نىمە؟" ))

 # ── 2. ChatPromptTemplate (كۆپ رول) ────────────────────── 
 chat_pt  =  ChatPromptTemplate . from_messages ([
    ( "system" ,  "سەن {رول} دىن {تىل}دا جاۋاپ بىرىدىغان ياردەمچىسەن." ),
     MessagesPlaceholder (variable_name= "chat_history" ),   # سۆھبەت تارىخى 
    ( "human" ,  "{سوئال}" ),
])

 formatted  =  chat_pt . format_messages (
    رول          =  "Python مۇتەخەسسىسى" ,
    تىل          =  "ئۇيغۇرچە" ,
    chat_history = [],
    سوئال        =  "List comprehension نىمە؟" 
)

 # ── 3. FewShotPromptTemplate (مىسال بىلەن) ─────────────── 
 examples  = [
    { "كىرگۈزمە" :  "ياخشى مەھسۇلات" ,  "چىقىم" :  "مۇسبەت" },
    { "كىرگۈزمە" :  "ناچار خىزمەت" ,   "چىقىم" :  "مەنپى" },
]

 example_pt  =  PromptTemplate (
    input_variables = [ "كىرگۈزمە" ,  "چىقىم" ],
    template        =  "تېكىست: {كىرگۈزمە}\nتويغۇ: {چىقىم}" 
)

 few_shot  =  FewShotPromptTemplate (
    examples         =  examples ,
    example_prompt   =  example_pt ,
    prefix           =  "تۆۋەندىكى مىسالغا ئاساسەن تويغۇ بەلگىلە:\n" ,
    suffix           =  "تېكىست: {كىرگۈزمە}\nتويغۇ:" ,
    input_variables  = [ "كىرگۈزمە" ]
)

 # ── 4. Partial Variables ───────────────────────────────── 
 partial_pt  =  chat_pt . partial (رول= "SQL مۇتەخەسسىسى" , تىل= "ئۇيغۇرچە" )
 # ئەمدى پەقەت سوئال يوللاش كېرەك

from   langchain_core.output_parsers   import  (
     StrOutputParser ,        # خام تېكىست 
     JsonOutputParser ,       # JSON dict 
     CommaSeparatedListOutputParser ,   # تىزىملىك 
)
 from   langchain.output_parsers   import   PydanticOutputParser 
 from   pydantic   import   BaseModel ,  Field 

 # ── 1. StrOutputParser ───────────────────────────────── 
 chain  =  chat_pt  |  claude  |  StrOutputParser ()
 text  =  chain . invoke ({ "سوئال" :  "سالام" })   # → str 

 # ── 2. Pydantic (تۈزۈملۈك) ──────────────────────────── 
 class   Recipe ( BaseModel ):
    ئىسمى:        str        =  Field (description= "تاماق ئىسمى" )
    مىقدارى:     int        =  Field (description= "ئادەم سانى" )
    قاداملار:    list[str]  =  Field (description= "قاداملار تىزىملىكى" )

 parser  =  PydanticOutputParser (pydantic_object= Recipe )

 prompt  =  ChatPromptTemplate . from_template (
     "{تاماق} نىڭ رېتسېپتىنى بىر.\n{format_instructions}" 
). partial (format_instructions= parser . get_format_instructions ())

 recipe_chain  =  prompt  |  gpt  |  parser 
 recipe :  Recipe  =  recipe_chain . invoke ({ "تاماق" :  "لاغمان" })
 print ( recipe .ئىسمى)     # "لاغمان" 
 print ( recipe .قاداملار)  # ["ئۇن", "گۆش", ...]

from   langchain_core.prompts          import   ChatPromptTemplate 
 from   langchain_core.output_parsers    import   StrOutputParser 
 from   langchain_core.runnables         import   RunnablePassthrough ,  RunnableParallel 
 from   langchain_openai                 import   ChatOpenAI 

 model  =  ChatOpenAI (model= "gpt-4o-mini" )

 # ── 1. ئاددىي زەنجىر (| ئوپىراتورى) ───────────────────── 
 simple_chain  = (
     ChatPromptTemplate . from_template ( "{سوئال} غا قىسقا جاۋاپ بەر." )
    |  model 
    |  StrOutputParser ()
)
 ans  =  simple_chain . invoke ({ "سوئال" :  "Python دېگەن نېمە?" })

 # ── 2. RunnableParallel (بىر ۋاقىتتا) ─────────────────── 
 parallel  =  RunnableParallel (
    ئۇيغۇرچە =  ChatPromptTemplate . from_template ( "{x} نى ئۇيغۇرچە چۈشەندۈر" ) |  model  |  StrOutputParser (),
    ئىنگلىزچە =  ChatPromptTemplate . from_template ( "explain {x} in English" ) |  model  |  StrOutputParser (),
)
 result  =  parallel . invoke ({ "x" :  "RAG" })
 # → {"ئۇيغۇرچە": "...", "ئىنگلىزچە": "..."} 

 # ── 3. RunnablePassthrough (ئۆزگەرتمەي يوللاش) ───────── 
 def   get_context ( query ):
     return   vectordb . similarity_search ( query )

 rag_chain  = (
    { "context" :  get_context ,  "سوئال" :  RunnablePassthrough ()}
    |  ChatPromptTemplate . from_template ( "{context}\n\nسوئال: {سوئال}" )
    |  model 
    |  StrOutputParser ()
)

 # ── 4. Fallback (خاتالىقتا باشقىسى) ─────────────────── 
 primary   =  ChatOpenAI (model= "gpt-4o" )
 fallback  =  ChatOpenAI (model= "gpt-4o-mini" )

 safe_model  =  primary . with_fallbacks ([ fallback ])

 # ── 5. Batch ئىجرا ────────────────────────────────────── 
 questions  = [
    { "سوئال" :  "Python نىمە؟" },
    { "سوئال" :  "JavaScript نىمە؟" },
    { "سوئال" :  "Rust نىمە؟" },
]
 answers  =  simple_chain . batch ( questions , config={ "max_concurrency" :  3 })

 # ── 6. Async ئىجرا ────────────────────────────────────── 
 import   asyncio 

 async def   main ():
     result  =  await   simple_chain . ainvoke ({ "سوئال" :  "سالام!" })
     print ( result )

 asyncio . run ( main ())

from   langchain_core.chat_history         import   BaseChatMessageHistory 
 from   langchain_community.chat_message_histories   import  (
     ChatMessageHistory ,        # RAM دا ساقلاش 
     RedisChatMessageHistory ,   # Redis دا ساقلاش 
     SQLChatMessageHistory ,     # SQL دا ساقلاش 
)
 from   langchain_core.runnables.history    import   RunnableWithMessageHistory 

 # ── 1. ئاددىي RAM خاتىرىسى ─────────────────────────────── 
 store  = {}   # session_id → ChatMessageHistory 

 def   get_session ( session_id :  str ) ->  BaseChatMessageHistory :
     if   session_id   not in   store :
         store [ session_id ] =  ChatMessageHistory ()
     return   store [ session_id ]

 prompt  =  ChatPromptTemplate . from_messages ([
    ( "system" ,  "سەن ئۇيغۇرچە ياردەمچىسەن." ),
     MessagesPlaceholder (variable_name= "history" ),
    ( "human" ,  "{input}" ),
])

 chain  =  prompt  |  model  |  StrOutputParser ()

 chain_with_history  =  RunnableWithMessageHistory (
     chain ,
     get_session ,
    input_messages_key   =  "input" ,
    history_messages_key =  "history" ,
)

 # ئىشلىتىش 
 config  = { "configurable" : { "session_id" :  "Idirak_001" }}

 r1  =  chain_with_history . invoke ({ "input" :  "مېنىڭ ئىسمىم Idirak" }, config= config )
 r2  =  chain_with_history . invoke ({ "input" :  "مېنىڭ ئىسمىم نېمە؟" }, config= config )
 print ( r2 )   # → "سىزنىڭ ئىسمىڭىز Idirak." 

 # ── 2. Redis دا ساقلاش (Production) ──────────────────── 
 redis_history  =  RedisChatMessageHistory (
    session_id =  "Idirak_001" ,
    url        =  "redis://localhost:6379" 
)

 # ── 3. خۇلاسىلاش خاتىرىسى (ئۇزۇن سۆھبەت ئۈچۈن) ──────── 
 from   langchain.memory   import   ConversationSummaryBufferMemory 

 summary_memory  =  ConversationSummaryBufferMemory (
    llm             =  model ,
    max_token_limit =  1000 ,    # بۇ چەكتىن ئاشسا خۇلاسىلايدۇ 
    return_messages =  True 
)

# ── Document Loaders ───────────────────────────────────── 
 from   langchain_community.document_loaders   import  (
     PyPDFLoader ,            # PDF 
     TextLoader ,             # .txt 
     WebBaseLoader ,          # تور بەت 
     UnstructuredWordDocumentLoader ,   # Word 
     CSVLoader ,              # CSV 
     DirectoryLoader ,        # پۈتۈن قىسىم 
)

 pdf_docs  =  PyPDFLoader ( "uyghur_history.pdf" ). load ()
 web_docs  =  WebBaseLoader ( "https://idirak.com" ). load ()

 # ── Text Splitters ──────────────────────────────────────── 
 from   langchain.text_splitter   import  (
     RecursiveCharacterTextSplitter ,   # سۈكۈتتىكى تاللاش 
     CharacterTextSplitter ,
     TokenTextSplitter ,                # تامغا ئاساسلىق 
     MarkdownHeaderTextSplitter ,       # Markdown ئاساسلىق 
)

 splitter  =  RecursiveCharacterTextSplitter (
    chunk_size    =  512 ,
    chunk_overlap =  64 ,
    separators    = [ "\n\n" ,  "\n" ,  "." ,  " " ,  "" ]
)
 chunks  =  splitter . split_documents ( pdf_docs )
 print ( f" {len(chunks)}  بۆلۈك ھاسىللاندى" )

 # ── Embeddings ──────────────────────────────────────────── 
 from   langchain_openai             import   OpenAIEmbeddings 
 from   langchain_community.embeddings   import   HuggingFaceEmbeddings 

 embed_openai  =  OpenAIEmbeddings (model= "text-embedding-3-small" )
 embed_local   =  HuggingFaceEmbeddings (     # ھەقسىز 
    model_name =  "sentence-transformers/all-MiniLM-L6-v2" 
)

 # ── Vector Stores ───────────────────────────────────────── 
 from   langchain_chroma     import   Chroma 
 from   langchain_community.vectorstores   import   FAISS ,  Pinecone 

 vectordb  =  Chroma . from_documents (
    documents  =  chunks ,
    embedding  =  embed_openai ,
    persist_directory =  "./my_vectordb" 
)

 # ── Retrievers ──────────────────────────────────────────── 
 basic_retriever  =  vectordb . as_retriever (
    search_type   =  "similarity" ,   # "mmr" | "similarity_score_threshold" 
    search_kwargs = { "k" :  5 }
)

 # MultiQueryRetriever — سوئالدىن كۆپ تۈرلۈك ئىزدەش 
 from   langchain.retrievers   import   MultiQueryRetriever 
 mq_retriever  =  MultiQueryRetriever . from_llm (
    retriever =  basic_retriever ,
    llm       =  model 
)

 # ContextualCompressionRetriever — ئالىنغان مەزمۇننى قىسقارت 
 from   langchain.retrievers                         import   ContextualCompressionRetriever 
 from   langchain.retrievers.document_compressors     import   LLMChainExtractor 
 compressor      =  LLMChainExtractor . from_llm ( model )
 comp_retriever  =  ContextualCompressionRetriever (
    base_compressor   =  compressor ,
    base_retriever    =  basic_retriever 
)

 # ── Conversational RAG Chain ───────────────────────────── 
 from   langchain.chains   import   create_retrieval_chain 
 from   langchain.chains.combine_documents   import   create_stuff_documents_chain 
 from   langchain.chains   import   create_history_aware_retriever 

 qa_prompt  =  ChatPromptTemplate . from_messages ([
    ( "system" ,  "پەقەت بىرىلگەن مەزمۇنغا ئاساسلانغان جاۋاپ بەر:\n{context}" ),
     MessagesPlaceholder ( "chat_history" ),
    ( "human" ,  "{input}" ),
])

 doc_chain  =  create_stuff_documents_chain ( model ,  qa_prompt )
 rag_chain  =  create_retrieval_chain ( basic_retriever ,  doc_chain )

 res  =  rag_chain . invoke ({ "input" :  "ئۇيغۇر تارىخى قانداق؟" ,  "chat_history" : []})
 print ( res [ "answer" ])
 print ( res [ "context" ])   # مەنبە ھۆججەتلىرى

from   langchain.agents    import   AgentExecutor ,  create_tool_calling_agent 
 from   langchain.tools     import   tool ,  StructuredTool 
 from   langchain_community.tools   import  (
     DuckDuckGoSearchRun ,
     WikipediaQueryRun ,
     PythonREPLTool ,
)

 # ── 1. @tool دېكوراتورى بىلەن ئۆز قورال ──────────────── 
 @tool 
 def   calculate_area ( length :  float ,  width :  float ) ->  float :
     """تىك تۆت بۇلۇڭنىڭ مەيدانىنى ھىسابلا. بىرلىكى كۋادرات مېتىر.""" 
     return   length  *  width 

 @tool 
 def   get_uyghur_date () ->  str :
     """ھازىرقى ۋاقىت-كۈننى قايتۇر.""" 
     from   datetime   import   datetime 
     return   datetime . now (). strftime ( "%Y-يىل %m-ئاي %d-كۈن" )

 # ── 2. قوراللار تىزىملىكى ──────────────────────────────── 
 tools  = [
     DuckDuckGoSearchRun (),
     WikipediaQueryRun (api_wrapper= WikipediaAPIWrapper ()),
     calculate_area ,
     get_uyghur_date ,
]

 # ── 3. Tool Calling Agent (ئەڭ يېڭى ئۇسۇل) ────────────── 
 agent_prompt  =  ChatPromptTemplate . from_messages ([
    ( "system" ,  "سەن ئۇيغۇرچە ياردەمچىسەن. قورالدىن ئىشلىت." ),
    ( "human" ,   "{input}" ),
     MessagesPlaceholder ( "agent_scratchpad" ),
])

 agent     =  create_tool_calling_agent ( model ,  tools ,  agent_prompt )
 executor  =  AgentExecutor (
    agent   =  agent ,
    tools   =  tools ,
    verbose =  True ,        # Thought/Action/Observation نى كۆرسەت 
    max_iterations     =  10 ,
    handle_parsing_errors =  True 
)

 result  =  executor . invoke ({
     "input" :  "ئۇيغۇرستان ھەققىدە ئىزدەپ ئۇيغۇرچە خۇلاسىلا" 
})
 print ( result [ "output" ])

 # ── 4. StructuredTool — مۇرەككەپ كىرگۈزمە ────────────── 
 from   pydantic   import   BaseModel 

 class   WeatherInput ( BaseModel ):
    شەھەر:   str 
    كۈن:     int  =  3    # مۆلچەر كۈنى 

 weather_tool  =  StructuredTool . from_function (
    func        =  get_weather_api ,
    name        =  "get_weather" ,
    description =  "شەھەرنىڭ ھاۋارايى مۆلچەرىنى ئال" ,
    args_schema =  WeatherInput ,
)

# ── 1. Streaming ───────────────────────────────────────── 
 chain  =  prompt  |  model  |  StrOutputParser ()

 # تامغا-تامغا چىقىش 
 for   chunk   in   chain . stream ({ "سوئال" :  "ئۇيغۇر تىلى ھەققىدە" }):
     print ( chunk , end= "" , flush= True )

 # Async Streaming (FastAPI ئۈچۈن) 
 from   fastapi               import   FastAPI 
 from   fastapi.responses     import   StreamingResponse 

 app  =  FastAPI ()

 @app.get ( "/stream" )
 async def   stream_endpoint ( q :  str ):
     async def   generate ():
         async for   chunk   in   chain . astream ({ "سوئال" :  q }):
             yield   f"data: {chunk}\n\n" 
     return   StreamingResponse ( generate (), media_type= "text/event-stream" )

 # ── 2. Custom Callback ─────────────────────────────────── 
 from   langchain_core.callbacks   import   BaseCallbackHandler 

 class   UyghurLogger ( BaseCallbackHandler ):
     def   on_llm_start ( self ,  serialized ,  prompts , ** kwargs ):
         print ( f"🚀 LLM باشلاندى: {prompts[0][:50]}..." )

     def   on_llm_end ( self ,  response , ** kwargs ):
         print ( f"✅ LLM تاماملاندى" )

     def   on_chain_error ( self ,  error , ** kwargs ):
         print ( f"❌ خاتالىق: {error}" )

 result  =  chain . invoke (
    { "سوئال" :  "سالام" },
    config={ "callbacks" : [ UyghurLogger ()]}
)

 # ── 3. LangSmith كۆزىتىش ──────────────────────────────── 
 # .env: LANGCHAIN_TRACING_V2=true, LANGCHAIN_API_KEY=ls__... 
 from   langsmith   import   traceable 

 @traceable (name= "uyghur_qa" )
 def   answer_question ( question :  str ) ->  str :
     return   chain . invoke ({ "سوئال" :  question })
 # smith.langchain.com دا ئىز كۆرۈنىدۇ

from   langgraph.graph           import   StateGraph ,  END 
 from   langgraph.prebuilt        import   create_react_agent 
 from   typing                    import   TypedDict ,  Annotated 
 import   operator 

 # ── 1. ھالەت ئانىقلاش ──────────────────────────────────── 
 class   AgentState ( TypedDict ):
    messages:   Annotated [ list ,  operator .add]
    next_step:  str 
    result:     str 

 # ── 2. تۈگۈن فۇنكسىيىلىرى ────────────────────────────── 
 def   researcher_node ( state :  AgentState ):
     """تور ئىزدەش تۈگۈنى""" 
     query     =  state [ "messages" ][- 1 ].content
     results   =  search_web ( query )
     return  { "messages" : [ AIMessage (content= results )]}

 def   writer_node ( state :  AgentState ):
     """يازغۇچى تۈگۈنى""" 
     context  =  state [ "messages" ]
     article  =  model . invoke ( context ).content
     return  { "result" :  article }

 def   route ( state :  AgentState ) ->  str :
     """قايسى تۈگۈنگە بارىش كېرەكلىكىنى بەلگىلە""" 
     if   "ئىزدە"   in   state [ "messages" ][- 1 ].content:
         return   "researcher" 
     return   "writer" 

 # ── 3. گراپ قۇرۇش ──────────────────────────────────────── 
 workflow  =  StateGraph ( AgentState )

 workflow . add_node ( "researcher" ,  researcher_node )
 workflow . add_node ( "writer" ,      writer_node )

 workflow . set_entry_point ( "researcher" )

 workflow . add_conditional_edges (
     "researcher" ,
     route ,
    { "researcher" :  "researcher" ,  "writer" :  "writer" }
)
 workflow . add_edge ( "writer" ,  END )

 graph  =  workflow . compile ()

 # ── 4. ئىجرا ────────────────────────────────────────────── 
 result  =  graph . invoke ({
     "messages" : [ HumanMessage (content= "ئۇيغۇر تارىخى ھەققىدە ئىزدەپ ماقالە يازغىن" )]
})
 print ( result [ "result" ])

# ── 1. Caching — يادروپلاش ─────────────────────────────── 
 from   langchain.globals         import   set_llm_cache 
 from   langchain_community.cache   import   InMemoryCache ,  RedisCache 

 set_llm_cache ( InMemoryCache ())    # ئوخشاش سوئال API غا قايتا بارمايدۇ 
 set_llm_cache ( RedisCache . from_client ( redis_client ))   # Production 

 # Semantic Cache — مەنالىق ئوخشاشتا يادروپلا 
 from   langchain_community.cache   import   GPTCache 
 set_llm_cache ( GPTCache ())   # ~ئوخشاش سوئاللارنى يادروپلايدۇ 

 # ── 2. خاتالىق بوستۇرۇش ───────────────────────────────── 
 from   langchain_core.runnables   import   RunnableWithFallbacks 

 robust_chain  = (
     chain 
    . with_retry (stop_after_attempt= 3 )           # قايتا سىناش 
    . with_fallbacks ([ backup_chain ])             # زاپاس 
    . with_config ({"timeout":  30 })                # ۋاقىت چەكى 
)

 # ── 3. تامغا ئىشلىتىشنى كۆزىتىش ──────────────────────── 
 from   langchain_community.callbacks   import   get_openai_callback 

 with   get_openai_callback ()  as   cb :
     chain . invoke ({ "سوئال" :  "Python لامبدا فۇنكسىيىسى نىمە؟" })
     print ( f"تامغا: {cb.total_tokens}, خارجىيەت: ${cb.total_cost:.4f}" )

 # ── 4. Prompt Caching (Claude) — 90% ئارزانلىق ─────────── 
 claude_cached  =  ChatAnthropic (
    model      =  "claude-sonnet-4-6" ,
    extra_headers = { "anthropic-beta" :  "prompt-caching-2024-07-31" }
)

 # ئۇزۇن system prompt نى يادروپلاش 
 system_with_cache  = {
     "type" :  "text" ,
     "text" :  "...ئۇزۇن system prompt..." ,
     "cache_control" : { "type" :  "ephemeral" }   # ← يادروپلا! 
}

 # ── 5. Async + Semaphore (يۈك كونترولى) ───────────────── 
 import   asyncio 

 async def   batch_process ( queries :  list [ str ],  max_concurrent = 5 ):
     sem  =  asyncio . Semaphore ( max_concurrent )

     async def   process_one ( q ):
         async with   sem :
             return   await   chain . ainvoke ({ "سوئال" :  q })

     tasks  = [ process_one ( q )  for   q   in   queries ]
     return   await   asyncio . gather (* tasks )