Package: ailingbot
🇬🇧English🇨🇳简体中文AilingBot - One-stop solution to empower your IM bot with AI.Table of ContentsWhat is AilingBotFeaturesQuick StartStart an AI chatbot in 5 minutesUsing DockerUsing PIPInstallationGenerate Configuration FileStart the ChatbotStart API ServiceUsing DockerUsing PIPInstallationGenerate Configuration FileStart the ServiceIntegrating with WeChat WorkUsing DockerUsing PIPInstallationGenerate Configuration FileModify Configuration FileStart the ServiceIntegrating with FeishuUsing DockerUsing PIPInstallationGenerate Configuration FileModify Configuration FileStart the ServiceIntegrating with DingTalkUsing DockerUsing PIPInstallationGenerate Configuration FileModify Configuration FileStart the ServiceIntegrating with SlackUsing DockerUsing PIPInstallationGenerate Configuration FileModify Configuration FileStart the Service📖User GuideMain ProcessMain ConceptsConfigurationConfiguration MethodsConfiguration MappingConfiguration ItemsGeneralBuilt-in Policy Configurationconversationdocument_qaModel ConfigurationOpenAICommand Line ToolsInitialize Configuration File (init)UsageOptionsView Current Configuration (config)UsageOptionsStart Command Line Bot (chat)UsageOptionsStart Webhook Service (serve)UsageOptionsStart API Service (api)UsageOptions🔌API💻Development GuideDevelopment GuidelinesDeveloping Chat PolicyDeveloping Channel🤔Frequently Asked Questions🎯RoadmapWhat is AilingBotAilingBot is an open-source engineering development framework and an all-in-one solution for integrating AI models into
IM chatbots. With AilingBot, you can:☕Code-free usage: Quickly integrate existing AI large-scale models into mainstream IM chatbots (such as WeChat
Work, Feishu, DingTalk, Slack etc.) to interact with AI models through IM chatbots and complete business
requirements. Currently, AilingBot has built-in capabilities for multi-turn dialogue and document knowledge Q&A, and
more capabilities will be added in the future.🛠️Secondary development: AilingBot provides a clear engineering architecture, interface definition, and necessary
basic components. You do not need to develop the engineering framework for large-scale model services from scratch.
You only need to implement your Chat Policy and complete end-to-end AI model empowerment to IM chatbots through simple
configurations. It also supports expanding to your own end (such as your own IM, web application, or mobile
application) by developing your own channel.Features💯Open source & Free: Completely open source and free.📦Ready to use: No need for development, with pre-installed capabilities to integrate with existing mainstream IM
and AI models.🔗LangChain Friendly: Easy to integrate with LangChain.🧩Modular: The project is organized in a modular way, with modules dependent on each other through abstract
protocols. Modules of the same type can be implemented by implementing the protocol, allowing for plug-and-play.💻Extensible: AilingBot can be extended to new usage scenarios and capabilities. For example, integrating with new
IMs, new AI models, or customizing your own chat policy.🔥High performance: AilingBot uses a coroutine-based asynchronous mode to improve system concurrency performance.
At the same time, system concurrency processing capabilities can be further improved through multi-processes.🔌API Integration: AilingBot provides a set of clear API interfaces for easy integration and collaboration with
other systems and processes.🚀 Quick StartStart an AI chatbot in 5 minutesBelow is a guide on how to quickly start an AI chatbot based on the command-line interface using AilingBot. The effect
is shown in the following figure:💡 First, you need to have an OpenAI API key. If you don't have one, refer to relevant materials on the Internet to
obtain it.Using Dockergitclonehttps://github.com/ericzhang-cn/ailingbot.gitailingbotcdailingbot
dockerbuild-tailingbot.
dockerrun-it--rm\-eAILINGBOT_POLICY__LLM__OPENAI_API_KEY={yourOpenAIAPIkey}\ailingbotpoetryrunailingbotchatUsing PIPInstallationpipinstallailingbotGenerate Configuration Fileailingbotinit--silence--overwriteThis will create a file calledsettings.tomlin the current directory, which is the configuration file for AilingBot.
Next, modify the necessary configurations. To start the bot, only one configuration is needed. Find the following
section insettings.toml:[policy.llm]_type="openai"model_name="gpt-3.5-turbo"openai_api_key=""temperature=0Change the value ofopenai_api_keyto your actual OpenAI API key.Start the ChatbotStart the chatbot with the following command:ailingbotchatStart API ServiceUsing Dockergitclonehttps://github.com/ericzhang-cn/ailingbot.gitailingbotcdailingbot
dockerbuild-tailingbot.
dockerrun-it--rm\-eAILINGBOT_POLICY__LLM__OPENAI_API_KEY={yourOpenAIAPIkey}\ailingbotpoetryrunailingbotapiUsing PIPInstallationpipinstallailingbotGenerate Configuration FileSame as starting the command line bot.Start the ServiceStart the bot using the following command:ailingbotapiNow, enterhttp://localhost:8080/docsin your browser to see the API documentation. (If it is not a local start,
please enterhttp://{your public IP}:8080/docs)Here is an example request:curl-X'POST'\'http://localhost:8080/chat/'\-H'accept: application/json'\-H'Content-Type: application/json'\-d'{"text": "你好"}'And the response:{"type":"text","conversation_id":"default_conversation","uuid":"afb35218-2978-404a-ab39-72a9db6f303b","ack_uuid":"3f09933c-e577-49a5-8f56-fa328daa136f","receiver_id":"anonymous","scope":"user","meta":{},"echo":{},"text":"你好！很高兴和你聊天。有什么我可以帮助你的吗？","reason":null,"suggestion":null}Integrating with WeChat WorkHere's a guide on how to quickly integrate the chatbot with WeChat Work.Using Dockergitclonehttps://github.com/ericzhang-cn/ailingbot.gitailingbotcdailingbot
dockerbuild-tailingbot.
dockerrun-d\-eAILINGBOT_POLICY__NAME=conversation\-eAILINGBOT_POLICY__HISTORY_SIZE=5\-eAILINGBOT_POLICY__LLM__OPENAI_API_KEY={yourOpenAIAPIkey}\-eAILINGBOT_CHANNEL__NAME=wechatwork\-eAILINGBOT_CHANNEL__CORPID={yourWeChatWorkrobot's corpid} \-e AILINGBOT_CHANNEL__CORPSECRET={your WeChat Work robot'scorpsecret}\-eAILINGBOT_CHANNEL__AGENTID={yourWeChatWorkrobot's agentid} \-e AILINGBOT_CHANNEL__TOKEN={your WeChat Work robot'swebhooktoken}\-eAILINGBOT_CHANNEL__AES_KEY={yourWeChatWorkrobot'swebhookaes_key}\-p8080:8080ailingbotpoetryrunailingbotserveUsing PIPInstallationpipinstallailingbotGenerate Configuration Fileailingbotinit--silence--overwriteModify Configuration FileOpensettings.toml, and fill in the following section with your WeChat Work robot's real information:[channel]name="wechatwork"corpid=""# Fill in with real informationcorpsecret=""# Fill in with real informationagentid=0# Fill in with real informationtoken=""# Fill in with real informationaes_key=""# Fill in with real informationIn thellmsection, fill in your OpenAI API Key:[policy.llm]_type="openai"model_name="gpt-3.5-turbo"openai_api_key=""# Fill in with your real OpenAI API Key heretemperature=0Start the ServiceailingbotserveFinally, we need to go to the WeChat Work admin console to configure the webhook address so that WeChat Work knows to
forward the received user messages to our webhook.
The webhook URL is:http(s)://your_public_IP:8080/webhook/wechatwork/event/After completing the above configuration, you can find the chatbot in WeChat Work and start chatting:Integrating with FeishuHere's a guide on how to quickly integrate the chatbot with Feishu and enable a new conversation policy: uploading
documents and performing knowledge-based question answering on them.Using Dockergitclonehttps://github.com/ericzhang-cn/ailingbot.gitailingbotcdailingbot
dockerbuild-tailingbot.
dockerrun-d\-eAILINGBOT_POLICY__NAME=document_qa\-eAILINGBOT_POLICY__CHUNK_SIZE=1000\-eAILINGBOT_POLICY__CHUNK_OVERLAP=0\-eAILINGBOT_POLICY__LLM__OPENAI_API_KEY={yourOpenAIAPIkey}\-eAILINGBOT_POLICY__LLM__MODEL_NAME=gpt-3.5-turbo-16k\-eAILINGBOT_CHANNEL__NAME=feishu\-eAILINGBOT_CHANNEL__APP_ID={yourFeishurobot's app id} \-e AILINGBOT_CHANNEL__APP_SECRET={your Feishu robot'sappsecret}\-eAILINGBOT_CHANNEL__VERIFICATION_TOKEN={yourFeishurobot'swebhookverificationtoken}\-p8080:8080ailingbotpoetryrunailingbotserveUsing PIPInstallationpipinstallailingbotGenerate Configuration Fileailingbotinit--silence--overwriteModify Configuration FileOpensettings.toml, and change thechannelsection to the following, filling in your Feishu robot's real
information:[channel]name="feishu"app_id=""# Fill in with real informationapp_secret=""# Fill in with real informationverification_token=""# Fill in with real informationReplace thepolicysection with the following document QA policy:[policy]name="document_qa"chunk_size=1000chunk_overlap=5Finally, it is recommended to use the 16k model when using the document QA policy. Therefore,
changepolicy.llm.model_nameto the following configuration:[policy.llm]_type="openai"model_name="gpt-3.5-turbo-16k"# Change to gpt-3.5-turbo-16kopenai_api_key=""# Fill in with real informationtemperature=0Start the ServiceailingbotserveFinally, we need to go to the Feishu admin console to configure the webhook address.
The webhook URL for Feishu is:http(s)://your_public_IP:8080/webhook/feishu/event/After completing the above configuration, you can find the chatbot in Feishu and start chatting:Integrating with DingTalkHere's a guide on how to quickly integrate the chatbot with DingTalk.Using Dockergitclonehttps://github.com/ericzhang-cn/ailingbot.gitailingbotcdailingbot
dockerbuild-tailingbot.
dockerrun-d\-eAILINGBOT_POLICY__NAME=conversation\-eAILINGBOT_POLICY__HISTORY_SIZE=5\-eAILINGBOT_POLICY__LLM__OPENAI_API_KEY={yourOpenAIAPIkey}\-eAILINGBOT_CHANNEL__NAME=dingtalk\-eAILINGBOT_CHANNEL__APP_KEY={yourDingTalkrobot's app key} \-e AILINGBOT_CHANNEL__APP_SECRET={your DingTalk robot'sappsecret}\-eAILINGBOT_CHANNEL__ROBOT_CODE={yourDingTalkrobot'srobotcode}\-p8080:8080ailingbotpoetryrunailingbotserveUsing PIPInstallationpipinstallailingbotGenerate Configuration Fileailingbotinit--silence--overwriteModify Configuration FileOpensettings.toml, and change thechannelsection to the following, filling in your DingTalk robot's real
information:[channel]name="dingtalk"app_key=""# Fill in with real informationapp_secret=""# Fill in with real informationrobot_code=""# Fill in with real informationStart the ServiceailingbotserveFinally, we need to go to the DingTalk admin console to configure the webhook address.
The webhook URL for DingTalk is:http(s)://your_public_IP:8080/webhook/dingtalk/event/After completing the above configuration, you can find the chatbot in DingTalk and start chatting:Integrating with SlackHere's a guide on how to quickly integrate the chatbot with Slack and enable a new conversation policy: uploading
documents and performing knowledge-based question answering on them.Using Dockergitclonehttps://github.com/ericzhang-cn/ailingbot.gitailingbotcdailingbot
dockerbuild-tailingbot.
dockerrun-d\-eAILINGBOT_POLICY__NAME=document_qa\-eAILINGBOT_POLICY__CHUNK_SIZE=1000\-eAILINGBOT_POLICY__CHUNK_OVERLAP=0\-eAILINGBOT_POLICY__LLM__OPENAI_API_KEY={yourOpenAIAPIkey}\-eAILINGBOT_POLICY__LLM__MODEL_NAME=gpt-3.5-turbo-16k\-eAILINGBOT_CHANNEL__NAME=slack\-eAILINGBOT_CHANNEL__VERIFICATION_TOKEN={yourSlackAppwebhookverificationtoken}\-eAILINGBOT_CHANNEL__OAUTH_TOKEN={yourSlackAppoauthtoken}\-p8080:8080ailingbotpoetryrunailingbotserveUsing PIPInstallationpipinstallailingbotGenerate Configuration Fileailingbotinit--silence--overwriteModify Configuration FileOpensettings.toml, and change thechannelsection to the following, filling in your Slack robot's real information:[channel]name="slack"verification_token=""# Fill in with real informationoauth_token=""# Fill in with real informationReplace thepolicysection with the following document QA policy:[policy]name="document_qa"chunk_size=1000chunk_overlap=5Finally, it is recommended to use the 16k model when using the document QA policy. Therefore,
changepolicy.llm.model_nameto the following configuration:[policy.llm]_type="openai"model_name="gpt-3.5-turbo-16k"# Change to gpt-3.5-turbo-16kopenai_api_key=""# Fill in with real informationtemperature=0Start the ServiceailingbotserveFinally, we need to go to the Slack admin console to configure the webhook address.
The webhook URL for Slack is:http(s)://your_public_IP:8080/webhook/slack/event/After completing the above configuration, you can find the chatbot in Slack and start chatting:📖User GuideMain ProcessThe main processing flow of AilingBot is as follows:First, the user sends a message to the IM bot.If a webhook is configured, the instant messaging tool will forward the request sent to the bot to the webhook
service address.The webhook service processes the original IM message and converts it into AilingBot's internal message format, which
is then sent to ChatBot.ChatBot processes the request and forms a response message based on the configured chat policy. During this process,
ChatBot may perform operations such as requesting a large language model, accessing a vector database, or calling an
external API to complete the request processing.ChatBot sends the response message to the IM Agent. The IM Agent is responsible for converting the AilingBot internal
response message format into a specific IM format and calling the IM open capability API to send the response
message.The IM bot displays the message to the user, completing the entire processing process.Main ConceptsIM bot: A capability built into most instant messaging tools that allows administrators to create a bot and
process user messages through a program.Channel: A channel represents different terminals, which can be an IM or a custom terminal (such as the web).Webhook: An HTTP(S) service used to receive user messages forwarded by IM bots. Different channels have their own
specifications for webhooks, so each channel requires its own webhook implementation.IM Agent: Used to call IM open capability APIs. Different IM open capability APIs are different, so each channel
requires a corresponding agent implementation.ChatBot: The core component used to receive and respond to user messages.Chat Policy: Defines how to respond to users and is called by ChatBot. A chat policy specifically defines the
robot's abilities, such as chitchat or knowledge Q&A.LLM: Large language model, such as OpenAI's ChatGPT and open ChatGLM, are all different large language models. The
large language model is a key component for implementing AI capabilities.ConfigurationConfiguration MethodsAilingBot can be configured in two ways:Using configuration files: AilingBot readssettings.tomlin the current directory as the configuration file
inTOMLformat. Please refer to the following section for specific configuration items.Using environment variables: AilingBot also reads configuration items in environment variables. Please refer to
the following section for a list of environment variables.💡 Both configuration files and environment variables can be used together. If a configuration item exists in both, the
environment variable takes precedence.Configuration MappingAll configurations have the following mappings between TOML keys and environment variables:All environment variables start withAILINGBOT_.Double underscores__are used as separators between levels.Underscores in configuration keys are preserved in environment variables.Case-insensitive.For example:The corresponding environment variable ofsome_confisAILINGBOT_SOME_CONF.The corresponding environment variable ofsome_conf.conf_1isAILINGBOT_SOME_CONF__CONF_1.The corresponding environment variable ofsome_conf.conf_1.subconfisAILINGBOT_SOME_CONF__CONF_1__SUBCONF.Configuration ItemsGeneralConfiguration ItemDescriptionTOMLEnvironment VariableLanguageLanguage code (Reference:http://www.lingoes.net/en/translator/langcode.htm)langAILINGBOT_LANGTimezoneTimezone code (Reference:https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)tzAILINGBOT_TZPolicy NamePredefined policy name or complete policy class pathpolicy.nameAILINGBOT_POLICY__NAMEChannel NamePredefined channel namechannel.nameAILINGBOT_CHANNEL__NAMEWebhook PathComplete class path of non-predefined channel webhookchannel.webhook_nameAILINGBOT_CHANNEL__WEBHOOK_NAMEAgent PathComplete class path of non-predefined channel agentchannel.agent_nameAILINGBOT_CHANNEL__AGENT_NAMEUvicorn ConfigAll uvicorn configurations (Reference:uvicorn settings). These configurations will be passed to uvicornuvicorn.*AILINGBOT_UVICORN__*Configuration example:lang="zh_CN"tz="Asia/Shanghai"[policy]name="conversation"# More policy configurations[channel]name="wechatwork"# More channel configurations[uvicorn]host="0.0.0.0"port=8080Built-in Policy ConfigurationconversationConversation uses LangChain's Conversation as the policy, which enables direct interaction with LLM and has a
conversation history context, enabling multi-turn conversations.Configuration ItemDescriptionTOMLEnvironment VariableHistory SizeIndicates how many rounds of historical conversations to keeppolicy.history_sizeAILINGBOT_POLICY__HISTORY_SIZEConfiguration example:# Use the conversation policy and keep 5 rounds of historical conversations[policy]name="conversation"history_size=5document_qaDocument_qa uses LangChain'sStuffas the policy.
Users can upload a document and then ask questions based on the document content.Configuration ItemDescriptionTOMLEnvironment VariableChunk SizeCorresponds to LangChain Splitter's chunk_sizepolicy.chunk_sizeAILINGBOT_POLICY__CHUNK_SIZEChunk OverlapCorresponds to LangChain Splitter's chunk_overlappolicy.chunk_overlapAILINGBOT_POLICY__CHUNK_OVERLAPConfiguration example:# Use the document_qa policy, with chunk_size and chunk_overlap set to 1000 and 0, respectively[policy]name="document_qa"chunk_size=1000chunk_overlap=0Model ConfigurationThe model configuration is consistent with LangChain. The following is an example.OpenAI[policy.llm]_type="openai"# Corresponding environment variable: AILINGBOT_POLICY__LLM___TYPEmodel_name="gpt-3.5-turbo"# Corresponding environment variable: AILINGBOT_POLICY__LLM__MODEL_NAMEopenai_api_key="sk-pd8I'msorry,itseemslikeyourmessagegotcutoff.Canyoupleaseprovidemewithmoreinformationorclarifyyourrequest?Command Line ToolsInitialize Configuration File (init)UsageTheinitcommand generates a configuration filesettings.tomlin the current directory. By default, the user will be
prompted interactively. You can use the--silenceoption to generate the configuration file directly using default
settings.Usage: ailingbot init [OPTIONS]

Initialize the AilingBot environment.

Options:
--silence    Without asking the user.
--overwrite  Overwrite existing file if a file with the same name already
exists.
--help       Show this message and exit.OptionsOptionDescriptionTypeRemarks--silenceGenerate the default configuration directly without asking the user.Flag--overwriteAllow overwriting thesettings.tomlfile in the current directory.FlagView Current Configuration (config)Theconfigcommand reads the current environment configuration (including the configuration file and environment
variables) and merges them.UsageUsage: ailingbot config [OPTIONS]

  Show current configuration information.

Options:
  -k, --config-key TEXT  Configuration key.
  --help                 Show this message and exit.OptionsOptionDescriptionTypeRemarks-k, --config-keyConfiguration keyStringIf not passed, the complete configuration information will be displayed.Start Command Line Bot (chat)Thechatcommand starts an interactive command-line bot for testing the current chat policy.UsageUsage: ailingbot chat [OPTIONS]

  Start an interactive bot conversation environment.

Options:
  --debug  Enable debug mode.
  --help   Show this message and exit.OptionsOptionDescriptionTypeRemarks--debugEnable debug modeFlagThe debug mode will output more information, such as the prompt.Start Webhook Service (serve)Theservecommand starts a Webhook HTTP server for interacting with specific IM.UsageUsage: ailingbot serve [OPTIONS]

  Run webhook server to receive events.

Options:
  --log-level [TRACE|DEBUG|INFO|SUCCESS|WARNING|ERROR|CRITICAL]
                                  The minimum severity level from which logged
                                  messages should be sent to(read from
                                  environment variable AILINGBOT_LOG_LEVEL if
                                  is not passed into).  [default: TRACE]
  --log-file TEXT                 STDOUT, STDERR, or file path(read from
                                  environment variable AILINGBOT_LOG_FILE if
                                  is not passed into).  [default: STDERR]
  --help                          Show this message and exit.OptionsOptionDescriptionTypeRemarks--log-levelThe minimum severity level from which logged messages should be sent to.StringBy default, all log levels will be displayed (TRACE).--log-fileThe location where logs are output.StringBy default, logs will be output to standard error (STDERR).Start API Service (api)Theapicommand starts the API HTTP server.UsageUsage: ailingbot api [OPTIONS]

Run endpoint server.

Options:
  --log-level [TRACE|DEBUG|INFO|SUCCESS|WARNING|ERROR|CRITICAL]
                                  The minimum severity level from which logged
                                  messages should be sent to(read from
                                  environment variable AILINGBOT_LOG_LEVEL if
                                  is not passed into).  [default: TRACE]
  --log-file TEXT                 STDOUT, STDERR, or file path(read from
                                  environment variable AILINGBOT_LOG_FILE if
                                  is not passed into).  [default: STDERR]
  --help                          Show this message and exit.OptionsOptionDescriptionTypeRemarks--log-levelDisplay log level, which will display logs at this level and aboveStringBy default, all levels are displayed (TRACE)--log-fileLog output locationStringBy default, logs are printed to standard error (STDERR)🔌APITBD💻Development GuideDevelopment GuidelinesTBDDeveloping Chat PolicyTBDDeveloping ChannelTBD🤔Frequently Asked QuestionsDue to the fact that WeChat Work does not support uploading file event callbacks, the built-indocument_qapolicy cannot be used for WeChat Work.The webhook of each IM requires a public IP. If you do not have one, you can consider testing locally through the "
intranet penetration" solution. Please refer to online resources for specific methods.We expect the chat policy to be stateless, and the state should be stored externally. However, in specific
implementations, the policy may still have local states (such as storing conversation history in local variables).
Therefore, when uvicorn has multiple worker processes, these local states cannot be shared because each process has a
separate chat policy instance, and a request from the same user may be responded to by different workers, leading to
unexpected behavior. To avoid this, please ensure that at least one of the following two conditions is met:Chat policy does not use local states.Only one uvicorn worker is started.🎯RoadmapProvide complete usage and developer documentation.Support more channels.WeChat WorkFeishuDingTalkSlackSupport more request message types.Text requestImage requestFile requestSupport more response message types.Text responseImage responseFile responseMarkdown responseTable responseDevelop more out-of-the-box chat policies.Multi-round conversation policyDocument question and answer policyDatabase question and answer policyOnline search question and answer policySupport calling standalone chat policy services through HTTP.Abstract basic componentsLarge language modelKnowledge baseToolsSupport local model deployment.ChatGLM-6BSupport API.Web management background and visual configuration management.Provide deployment capability based on Docker containers.Enhance the observability and controllability of the system.Complete test cases.